Docs Setup

Quizfreely Docs

User & SSH Key

To set up an ssh key for quizfreely/docs’ deploy-production workflow/GitHub action which builds the documentation site and uploads it to our server:

# on the server
adduser --disabled-password quizfreely-docs

# on your machine
ssh-keygen -t ed25519 -C "quizfreely-docs-gh-actions" -f qzfr_docs_key
# if it asks for a passphrase or blank for no passphrase, choose no passphrase

# when its done you get `qzfr_docs_key` and `qzfr_docs_key.pub`,
# copy the contents of `qzfr_docs_key.pub` (the public key)

# i personally do `nvim qzfr_docs_key.pub` then copy the whole thing using gg V G y

# on the server
su quizfreely-docs
mkdir -p ~/.ssh/
touch ~/.ssh/authorized_keys
nvim ~/.ssh/authorized_keys # edit ~/.ssh/authorized_keys
# paste the public key into that file

Now copy the private key (qzfr_docs_key) into a GitHub environment secret.

The production deployment workflow/GitHub-action uses the production environment. Go under Repository Settings > Environments > Production > Environment secrets, and create an environment secret named PROD_SERVER_NONROOT_SSH_KEY with the value of the copied private key (contents of qzfr_docs_key).

When you’re done saving the public key on the server and the private key into a repository environment secret, you can delete qzfr_docs_key and qzfr_docs_key.pub from your machine.

Folders & Permissions

# back to root
# you might need to run `exit` if you're still the `quizfreely-docs` user
mkdir -p /srv/quizfreely-docs/www

sudo chown -R quizfreely-docs:quizfreely-docs /srv/quizfreely-docs/www
sudo chmod 755 /srv/quizfreely-docs

Server Config

Now to configure our server/reverse proxy, caddy, to serve the static files for the docs site, edit /etc/caddy/Caddyfile

quizfreely.org {
    # other stuff

    handle_path /docs* {
        root * /srv/quizfreely-docs/www
        file_server
    }
}

Then reload caddy

systemctl reload caddy

Notes

Make sure the server has rsync: apt install rsync

If rsync runs on the remote server/gh actions runner but says “rsync: command not found”, it means the server doesn’t have rsync, but the remote server/gh actions runner does.