Quick Start

This document will go over the quickest way to get this platform up and running. Here we will choose the simplest approach for automation and hosting, which is to use GitHub Actions. Note, however, that there are alternatives to this approach, as detailed under the Automation and Hosting sections.

Need a quicker quick start?

This document recommends a double-repository approach, which separates your platform into a "site repository" and a "data repository". This is a good practice in general, and provides several logistical benefits. However, a simpler single-repository approach may be preferred if you just want to try out Open SDG locally. In this case, see the open-sdg-simple-starter project.

Signing up and creating repositories

  1. If you don't already have a Github.com account, go to Github.com to sign up and then log in.
  2. Go to the site starter and click the green "Use this template" button.
  3. Next you will be prompted to choose a name for your new repository. This will affect the URL at which you access the site later, so choose carefully. A suggestion might be: sdg-site-australia (adjusted for your country). Note that you can change this later if needed.
  4. Enter a description if you would like. Leave "Public" selected, and click "Create repository from template".
    • Bookmark the created repository -- this is your "site repository".
  5. Go to the data starter and click the green "Use this template" button.
  6. As before, choose a name. This one should refer to "data" instead of "site" (eg, sdg-data-australia). As before, leave "Public" selected and click "Create repository from template".
    • Bookmark the created repository -- this is your "data repository".

Creating an access token

This step is temporarily necessary because of a bug involving GitHub Actions and GitHub Pages. The bug is being discussed in this GitHub discussion thread.

  1. Create an access token described in this official GitHub documentation. Notes:
    • Select the repo permission, as indicated in those instructions.
    • Save the token somewhere private.
  2. Copy the access token so that you can paste in the next steps.
  3. Go to the site repository you bookmarked earlier.
  4. Under the repository name, click "Settings".
  5. In the left sidebar, click "Secrets".
  6. Click "Add a new secret".
  7. Under "Name", type the following (case-sensitive): token
  8. Under "Value", paste in the access token you copied earlier.
  9. Click the green "Add secret" button.
  10. Repeat all the steps above, but for the "data" repository you bookmarked earlier.

Update the data repository configuration

This step is necessary before continuing, and also serves to demonstrate how to edit files on Github.com.

  1. Go to the data repository.
  2. In the list of files, click on config_data.yml.
  3. Click the pencil icon on the right (You can find it next to the History button.)
  4. Adjust the list of language codes under languages by adding or changing as needed. If you would like multiple languages, they should be one per line, like so:

    languages: - fr - es

  5. If you did not need to adjust the list of language codes, simply make any other change in the file. For example, add a new line at the top: # This is a comment

  6. Towards the bottom, select "Create a new branch for this commit and start a pull request."
  7. Beneath this, click "Propose file changes".
  8. Click on the green "Create pull request" button.
  9. Wait a moment to see the message that says "Test PRs / test (pull_request) - in progress"
  10. Wait until you see "All checks have passed". This takes about 5 minutes.
  11. Click on the green "Merge pull request" button.

Next, you will need to edit the deploy-to-staging workflow to allow the site repository to be rebuilt automatically once a change has been made in the data repository:

  1. In the list of files in the data repository, click on .github/workflows.
  2. Click on deploy-to-staging.yml.
  3. Click the pencil to edit the file.
  4. Make changes to the file by following the instructions in the notes.
  5. Towards the bottom, select "Create a new branch for this commit and start a pull request."
  6. Beneath this, click "Propose file changes".
  7. Click on the green "Create pull request" button.
  8. Wait a moment to see the message that says "Test PRs / test (pull_request) - in progress"
  9. Wait until you see "All checks have passed". This takes about 5 minutes.
  10. Click on the green "Merge pull request" button.

This is a commonly-used way to edit files in GitHub. In summary, the steps are:

  • Find the file
  • Edit the file
  • Create the pull request
  • Merge the pull request

Update the site repository configuration

  1. Go to the site repository.
  2. In the list of files, click on _config.yml.
  3. Click the pencil icon on the right (You can find it next to the History button.)
  4. You will see some instructions in the file. Update the code as directed.
  5. In particular, adjust the language codes under languages in the same way you did with the data repository.
  6. Towards the bottom, select "Create a new branch for this commit and start a pull request."
  7. Beneath this, click "Propose file changes".
  8. Click on the green "Create pull request" button.
  9. Wait a moment to see the message that says "Test PRs / test (pull_request) - in progress"
  10. Wait until you see "All checks have passed". This takes about 5 minutes.
  11. Click on the green "Merge pull request" button.

View the site

  1. GitHub will now build and publish the site. Wait about 5 minutes.
  2. Go to the site repository.
  3. Under the repository name, click "Settings".
  4. Scroll down to the "GitHub Pages" section.
  5. You should see "Your site is published at" next to a link.
  6. Click that link to view your site.

Turn on automated testing

Both the site repository and the data repository can benefit from automated tests. Automated tests will ensure that changes do not break your site. Use the following steps to turn this on:

  1. Go to the data repository
  2. Under the repository name, click "Settings".
  3. In the left sidebar, click "Branches".
  4. Make sure the "default" branch is: develop
  5. Under "Branch protection rules" click "Add rule"
  6. Under "Branch name pattern" enter develop
  7. Check the box "Require status checks to pass before merging"
  8. Under "Status checks found in the last week for this repository" check the box for "test".
  9. Click the green "Create" button.
  10. Repeat the above steps, but for the site repository.

Results

At this point, any new proposed file changes in the repositories will trigger the automated tests. Also, when approved (aka "merged") the updated builds are automatically deployed to "GitHub Pages". These "GitHub Pages" URLs are your staging environments.

Possible next steps?

  1. Add data and metadata to the data repository
  2. Tweak and customise the site repository as needed
  3. Set up separate "production" environments