Deployment Overview
This section is for server administrators setting up or maintaining the docs infrastructure. Member developers don't need any of this.
What needs to be set up once
Server setup
Setting up a Debian server with nginx from scratch
Cloudflare
Setting up a Cloudflare tunnel pointing docs.trickfirerobotics.com to allow public access
Auto-deployment
Automatic deployment from GitHub push to main using a self-hosted GitHub runner on the server
Infrastructure at a glance
- Server: Debian, any cloud provider or on-prem
- Docs directory:
/home/trickfire/docs/(the cloned repo) - Web server: nginx on
localhost:80, not exposed to the internet - Public access: Cloudflare tunnel →
docs.trickfirerobotics.com - CI runner: GitHub Actions self-hosted, label
docs, runs on the same machine
Setup order
- Server Setup - provision the server, clone the repo, install dependencies, set up nginx
- Cloudflare Tunnel - install
cloudflared, create tunnel, point DNS - GitHub Actions Runner - register the runner so CI jobs can run on this machine
After those three steps, pushing docs to any connected member repo will automatically update the live site.
Ongoing maintenance
| Task | How |
|---|---|
| Update cli | Push to main in this repo - deploy.yml handles it |
| Add a new project | Member dev runs trickfire-docs init and pushes |
| Remove a project | Delete /home/trickfire/docs/content/<repo> and rebuild |
| Rebuild manually | ssh server 'bash /home/trickfire/docs/scripts/build.sh' |
| Check runner status | GitHub → Settings → Actions → Runners |
GitHub Runner
A self-hosted GitHub Actions runner on the docs server processes both the sync-docs reusable workflow (called by member repos) and the deploy workflow (triggered by changes to this repo). The runner needs the label docs so the workflow runs-on: [self-hosted, docs] target resolves correctly.
Register the runner
Go to the TrickFire Robotics organisation → Settings → Actions → Runners → New self-hosted runner, select the server's CPU architecture, and follow the commands shown. When prompted for labels, add docs (keep self-hosted too).
$ mkdir -p ~/docs-runner && cd ~/docs
# paste the download + configure commands from GitHub
# when asked for labels:
# Enter any additional labels: docsInstall as a systemd service
$ sudo ./svc.sh install
$ sudo ./svc.sh start
$ sudo systemctl status actions.runner.*