Wiki

DO NOT ADD THE WIKI PASSWORD TO THE WIKI

Along with other web resources, this site is served from the lab’s Digital ocean droplet. More specifically, as a static site which is rebuilt automatically from pushes to a git repository hosted on the droplet itself.

Contributing

Site content can be updated as simply as contributing to the repository (content will only be rebuilt from pushes to main). However, you first need to gain access. This is done using an ssh key pair. The following steps require ssh and git, both of which should already be on any development machine.

  1. navigate to your ~/.ssh directory (create it if it doesn’t exist)
  2. generate an ssh key pair using ssh-keygen
    • this will create two files using the name provided, I suggest using id_bci_droplet_git
  3. add the key to your user ssh configuration
    • open or create ~/.ssh/config
    • add the following block:
Host droplet-git
	HostName droplet.bci4kids.ca
	User git
	PubkeyAuthentication yes
	IdentityFile ~/.ssh/id_bci_droplet_git
  1. copy your public key to the droplet (working from your ~/.ssh directory)
    • ssh-copy-id -i id_bci_droplet_git droplet-git
    • when prompted, enter the password which was given to you (or poke Twig for it)

ssh-copy-id is a bash utility and might not be available in all environments. If you don’t have use of it, you will have to manually append the contents of your public key to /home/wiki/.ssh/authorized_keys on the droplet by logging in with the password

Once configured, you should be able to clone, fetch, pull from, and push to the repository without a password. To get started:

git clone ssh://droplet-git/~/wiki.git

Editing the Site

While the plain markdown may be easy enough to visualize, you won’t be able to see updates as you edit without setting up your local development environment. See the Hugo installation guides. The Hugo docs will also be your best resource for any questions on how the site works.

Deployment Configuration

This wiki site is hosted in a slightly more advanced (simpler and easier to maintain) manner than the general documented process.

Git User

Key to this setup is a separate git user on the droplet, created to facilitate access to a repository. The wiki.git repository itself lives in their home directory. By cloning it, you are simply accessing those files. A symbolic link then provides site content to /var/www/wiki.bci4kids.ca (read + execute privileges must be granted for all users with chmod). In this way, anyone can contribute to the site from a common dummy user without requiring super user privileges.

Post-Receive Hook

The script invoked by git after any push to the repo, this application uses a slightly more advanced version of the example given on the general deployment page.

#!/bin/bash

export GEM_HOME=$HOME/gems
PATH="$HOME/gems/bin:$PATH"

WORK_TREE=$HOME/wiki-worktree/
GIT_DIR=$HOME/wiki.git
DESTINATION=$HOME/wiki

while read oldrev newref ref
do
        BRANCH=$(git rev-parse --symbolic --abbrev-ref $ref)

        if [[ $BRANCH == "main" ]]; then
                echo "Main pushed, redeploying..."

                if [[ ! -d $WORK_TREE ]]; then
                        mkdir $WORK_TREE || exit 1
                fi
                echo "Populating build files..."
                git --work-tree=$WORK_TREE --git-dir=$GIT_DIR checkout -f || exit 1

                cd $WORK_TREE
                echo "Rebuilding site..."
                hugo -d $DESTINATION --cleanDestinationDir || exit 1

                cd ..
                echo "Cleaning build files..."
                rm -rf $WORK_TREE || exit 1
        else
                echo "Pushed to ${BRANCH}"
        fi
done

Nginx Server Block

A slight variation on the example block for static sites, this configuration tries for .html and local index files before defaulting to the 404.

server {
  root /var/www/wiki.bci4kids.ca;
  error_page 404 /404.html;
  index index.html;

  server_name wiki.bci4kids.ca www.wiki.bci4kids.ca;

  if ($host = www.wiki.bci4kids.ca) {
    return 301 https://wiki.bci4kids.ca$request_uri;
  }

  location / {
    try_files $uri $uri.html $uri/index.html =404;
  }

  location /404.html {
    internal;
  }
...
# certbot blocks