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 are to use CircleCI.com and Github.com. Note, however, that there are alternatives to this approach, as detailed under the Automation and Hosting sections.

Downloading Git

Windows

You will first need to install Git for Windows.

Mac

You will first need to install Git for Mac.

Note for Mac users: Once you click the download file you might be faced with an error saying that the installer "can’t be opened because it is from an unidentified developer". To resolve this issue, right click on the installer and click Open. This will bypass the error.

Signing up and creating forks

  1. If you don't already have a Github.com account, go to Github.com to sign up and then log in.
  2. In the same browser, go to CircleCI.com and click "Log In With Github". Accept any prompts until you are logged in.
  3. Go here and click "Fork" in the upper right. Choose your username to fork the project to your account.
    • Bookmark the forked repository -- this is your "site repository".
  4. Go here and click "Fork" in the upper right. Choose your username to fork the project to your account.
    • Bookmark the forked repository -- this is your "data repository".

Create SSH keys

This part may be painful if you are not accustomed to command-line work. But don't worry - it is pretty fast.

  1. Open your operating system's Terminal application (use Git BASH, if on Windows).

  2. Create the SSH keys by entering the command below, substituting my-email-address@example.com with the email address bound to your GitHub account. It might be worth creating a new folder for your keys:

    ssh-keygen -m pem -t rsa -b 4096 -C "my-email-address@example.com"

    1. When prompted "Enter file in which to save the key", enter my-site-key
    2. When prompted "Enter passphrase", just hit Enter.
    3. When prompted "Enter same passphrase again", just hit Enter again.
    4. Repeat the previous steps, only use my-data-key instead of my-site-key.

Confirm that 4 files have been created:

  • my-site-key
  • my-site-key.pub
  • my-data-key
  • my-data-key.pub

Add the SSH keys to Github.com

  1. Go to your "site repository" on Github.com that you bookmarked earlier
    1. Click "Settings" near the top-right.
    2. Click "Deploy keys" in the left menu.
    3. Click "Add deploy key"
    4. For "Title" enter anything, such as CircleCI key
    5. For "Key" paste in the contents of my-site-key.pub (created earlier)
      • Tip: A quick way to see the contents of the file is to go back to the terminal and enter: cat my-site-key.pub. Drag-select this output to copy it into your clipboard. On MacOS you can use cat my-site-key.pub | pbcopy to copy the contents of my-site-key.pub straight to your clipboard
    6. Check "Allow write access"
    7. Click "Add key"
    8. Select and copy the "Fingerprint" that appears (you may need to refresh the page)
  2. Click "Code" near the top left to get back to the list of files
    1. In the list of files, drill down to the .circleci/config.yml file: .circleci └─config.yml
    2. On the right, click the Pencil icon ("Edit this file").
    3. Paste the copied "Fingerprint" over PASTE_STAGING_FINGERPRINT_HERE.
    4. At the bottom, click "Commit changes".
  3. Repeat the above steps, but this time for the "data repository", and using the contents of my-data-key.pub instead.

Add projects to CircleCI.com

  1. Go to the CircleCI dashboard.
  2. In the left sidebar, click "Add Projects".
  3. Across from "open-sdg-site-starter" click "Set Up Project".
    1. Scroll down and click "Start Building".
    2. At this point, CircleCI will attempt to "build" the project, and will fail. You can ignore this and continue below.
    3. Click the gear icon in the upper right.
    4. Click "SSH Permissions" in the left sidebar.
    5. Click "Add SSH Key".
    6. Under "Hostname" enter: gh-staging
    7. Under "Private key", enter the contents of my-site-key (the file without the ".pub", created earlier)
    8. Click "Add SSH key".
  4. Go back to step #3 above and repeat the process with the "open-sdg-data-starter" repository.

Update the deployment scripts

  1. Go to your fork of the data repository (bookmarked earlier).
    1. In the list of files, drill down to the scripts/deploy/circleci/deploy_staging.sh file: scripts └─deploy └─circleci └─deploy_staging.sh
    2. On the right, click the Pencil icon ("Edit this file").
    3. Update the file as directed in the comments.
    4. At the bottom, click "Commit changes".
  2. Repeat these steps for the site repository (bookmarked earlier).

Update the site Jekyll configuration

  1. Go to your fork of the site repository (bookmarked earlier).
  2. In the list of files, click _config.yml.
  3. On the right, click the Pencil icon ("Edit this file").
  4. Update the file as directed in the comments.
  5. At the bottom, click "Commit changes".

View the site

  1. CircleCI and Github will now build and publish the site. Wait about 5 minutes.
  2. View site at: https://my-github-org.github.io/open-sdg-site-starter/ (replacing "my-github-org" as needed).

Results

At this point, any new updates in the "develop" branches of the repositories will trigger "builds" which automatically deploy to the github.io URLs. These github.io URLs are your staging environments.

Possible next steps?

  1. Turn on automation in your repositories
  2. Add data and metadata to the data repository
  3. Tweak and customise the site repository as needed
  4. Set up the "master" branch to deploy to a separate "production" environment