Skip to content

Creating a New Area

This document contains instructions for creating a new top-level OSG website via GitHub Pages and deploying it automatically with Travis-CI. This document assumes that you are an administrator of the opensciencegrid GitHub organization. Before starting, make sure that you have the git and gem tools installed.

  1. Create a new public repository in the opensciencegrid organization (referred to as <REPO NAME> in the rest of this document)

    1. Check the box marked Initialize this repository with a README
  2. Identify the repository as using mkdocs:

    1. On the repository home page (i.e., https://github.com/opensciencegrid/<REPO NAME>), click the gear button in the top right (next to "About")
    2. In the topics field, add mkdocs
    3. Click the “Save Changes” button
  3. Clone the repository and cd into the directory:

    git clone https://github.com/opensciencegrid/<REPO NAME>.git
    cd <REPO NAME>
    
  4. Create a gh-pages branch in the GitHub repository:

    git push origin master:gh-pages
    
  5. Update the contents of README.md and populate the LICENSE file with a Creative Commons Attribution 4.0 license:

    wget https://creativecommons.org/licenses/by/4.0/legalcode.txt > LICENSE
    
  6. Create and encrypt the repository deploy key

    1. Generate the repository deploy key:

      ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy-key -N ''
      
    2. Install the travis gem:

      gem install travis
      
    3. Login using your GitHub credentials:

      travis login --com
      
    4. Enable the repository in Travis:

      travis enable --com -r opensciencegrid/<REPO NAME>
      
    5. Encrypt the deploy key and temporarily save the output (you will need the hashes later for .travis.env):

      travis encrypt-file --com deploy-key
      
    6. Stage and commit your files:

      git add LICENSE README.md deploy-key.enc
      git commit -m "Prepare the repository for Travis-CI deployment"
      

      Danger

      Do NOT commit the unencrypted deploy-key!

    7. Add the contents of deploy-key.pub to your repository's list of deploy keys. Make sure to check Allow write access.

  7. Follow these instructions to add the doc-ci-scripts sub-module

  8. Create mkdocs.yml containing the following:

    site_name: <TITLE OF YOUR SITE>
    site_url: https://opensciencegrid.org/<REPO NAME>
    repo_name: https://github.com/opensciencegrid/<REPO NAME>
    theme:
      name: material
    
    pages:
      - Home: 'index.md'
    
    markdown_extensions:
      - admonition
      - codehilite:
          guess_lang: False
      - meta
      - toc:
          permalink: True
    
  9. Create a docs directory containing an index.md that will be your home page.

  10. Stage and commit these changes:

    git add mkdocs.yml docs/index.md
    git commit -m "Staging initial web page contents"
    
  11. Push local changes to the GitHub repository:

    git push origin master
    

    Your documents should be shortly available at https://www.opensciencegrid.org/<REPO NAME>

Creating an ITB Area

This section describes creating an ITB repository for a documentation area created in the previous section

  1. Create a new repository in the opensciencegrid organization and name it <REPO NAME>-itb. For example, an ITB area for the docs repository has a repository name of docs-itb. The ITB repository will be referred to as <ITB REPO NAME> in the rest of this document.

    1. Check the box marked Initialize this repository with a README
    2. Once created, add the mkdocs topic by clicking on the "Add topics" button
  2. Clone the repository and cd into the directory:

    git clone [email protected]:opensciencegrid/<ITB REPO NAME>
    cd <ITB REPO NAME>
    
  3. Create a gh-pages branch in the GitHub repository:

    git push origin master:gh-pages
    
  4. Update the contents of README.md

  5. In the non-ITB repository, create and encrypt the ITB repository deploy key

    1. cd into the non-ITB repository and generate the ITB deploy key

      cd <REPO NAME>
      ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy-itb
      
    2. Install the travis gem:

      gem install travis
      
    3. Encrypt the deploy key:

      travis encrypt-file deploy-itb
      
    4. Update .travis.env with the appropriate ITB values

    5. Add and commit your files:

      git add .travis.env deploy-itb.enc
      git commit -m "Add ITB deployment"
      

      Danger

      Do NOT commit the unencrypted deploy-itb!

  6. Add deploy-itb.pub to the ITB repository's list of deploy keys. Make sure to check Allow write access.

  7. Still in the non-ITB repository, push your local changes to the GitHub repository

    git push origin master
    

    Your documents should be shortly available at https://www.opensciencegrid.org/<REPO NAME>