Skip to content

Source: deploy/README.md. Edit it there; this page is generated at build time.

Server config ​

The box's nginx vhost and PHP-FPM pool, kept here so they are reviewed and versioned like the code they serve. They are installed by root, by hand — the deploy user has no sudo, and these change rarely enough that automating the install would buy nothing but a privileged step in every deploy.

FileInstalled at
nginx/blog-filament.conf/etc/nginx/sites-available/blog-filament, symlinked into sites-enabled/
php-fpm/blog-filament.conf/etc/php/8.5/fpm/pool.d/blog-filament.conf
runner/job-started.sh/etc/blog-filament/runner-job-started.sh (see below)

Two files here are not installed by hand, because the deploy installs them as deploy on every release (docs/adr/0009):

FileWhat it becomes
recipe/runtime.phpDeployer tasks, required by deploy.php: the crontab line and worker:install
systemd/blog-filament-worker.service~deploy/.config/systemd/user/, enabled and started

The one root step they need, once, before the first deploy: lingering lets deploy's systemd user manager start at boot rather than only while someone is logged in.

sh
loginctl enable-linger deploy
sh
install -m 644 nginx/blog-filament.conf   /etc/nginx/sites-available/blog-filament
install -m 644 php-fpm/blog-filament.conf /etc/php/8.5/fpm/pool.d/blog-filament.conf
php-fpm8.5 -t && systemctl reload php8.5-fpm
nginx -t && systemctl reload nginx

An edit made on the box and not here is lost the next time someone installs from here, so change the file in the repo first.

Two things hold only as a pair and break silently if one is changed alone:

  • $realpath_root in the vhost is the whole opcache strategy. Swap it for $document_root and deploys still succeed — while serving the previous release. See docs/research/deploy-tooling.md.
  • The front proxy's address (10.37.40.20) is trusted in bootstrap/app.php. If the proxy moves, the site keeps working but every generated URL turns http://. tests/Feature/TrustedProxyTest.php pins the address the app trusts; it cannot know the address the proxy actually has.
  • try_files in the vhost's /robots.txt block is what lets the route answer. public/robots.txt is gone (#46), and without the fallback nginx 404s the path. Its error_page 404 then renders Laravel's robots.txt under a 404 status. The body looks right in a browser, and crawlers ignore it. Check with curl -I, not by reading it.

TLS lives on the front proxy, not here ​

Traffic runs Cloudflare → the front proxy (119.18.36.16:443, internally 10.37.40.20) → this container on :80 over a private bridge. The container has certbot installed but holds no certificate and listens on no TLS port, so there is nothing to renew here. The origin certificate is Let's Encrypt and lives on the proxy (expiring 2026-12-05 when checked on 2026-09-19), so renewal has to be set up on the proxy: a working certbot renew timer and a deploy hook that reloads the proxy. The Cloudflare edge certificate renews by itself.

The Actions runner ​

Tag-triggered deploys run on a self-hosted runner on the box, registered to this repo (not an organisation) with the label filament-prod. It runs as deploy, so a deploy writes a tree the app can read without sudo — which also means any job it accepts runs as the owner of every release. runner/job-started.sh is what limits that: the runner calls it before each job and fails the job unless it is deploy.yml at a v* tag.

Nothing in GitHub can enforce that for this repo: runner groups need an organisation on a paid plan, and branch protection 403s on a free private repo. Without the hook, any pushed branch whose workflow says runs-on: filament-prod runs on the box. Fork PRs cannot reach it either way — workflows from forks of this private repo are off. A tag pusher is still trusted; this is the same boundary docs/adr/0007 draws around the env key.

The runner lives in /home/deploy/actions-runner, with its checkouts in _work/ there, well away from /var/www/blog-filament. It auto-updates, which it must: GitHub stops sending jobs to a runner more than a release or so behind.

Installing it, as deploy. The version only has to be current on day one — after that the runner updates itself. Take the checksum from the release's asset list, not from here, when the version changes.

sh
mkdir -p ~/actions-runner && cd ~/actions-runner
curl -fsSLo runner.tgz https://github.com/actions/runner/releases/download/v2.337.0/actions-runner-linux-x64-2.337.0.tar.gz
echo '70920811a4f8ad4328818682bca5c6469c1c942fab52448868071d0063816613  runner.tgz' | sha256sum -c
tar xzf runner.tgz && rm runner.tgz

Registering needs a one-hour token. From a machine with gh, piped so the token never lands in a file or a shell history:

sh
gh api -X POST repos/muhammad-mem/blog-filament/actions/runners/registration-token --jq .token \
  | ssh -p 5497 deploy@119.18.36.16 'read -r token && cd ~/actions-runner && ./config.sh --unattended \
      --url https://github.com/muhammad-mem/blog-filament --token "$token" \
      --name ct155 --labels filament-prod --work _work'

Then as root, once, from a copy of this directory — the hook first, installed where deploy cannot edit it, then the service. The runner reads .env only at start, so a hook added to a running service does nothing until it is restarted.

sh
install -d -m 0750 -o root -g deploy /etc/blog-filament
install -m 755 -o root -g root runner/job-started.sh /etc/blog-filament/runner-job-started.sh
echo 'ACTIONS_RUNNER_HOOK_JOB_STARTED=/etc/blog-filament/runner-job-started.sh' >> /home/deploy/actions-runner/.env
cd /home/deploy/actions-runner && ./svc.sh install deploy && ./svc.sh start

/etc/blog-filament is the directory docs/adr/0007 puts the env key in; 0750 root:deploy is its mode there too, so creating it here first changes nothing.

Releases ​

deploy.php at the repo root is the release contract, and docs/adr/0010 explains it step by step. Pushing a v* tag runs it on the runner above. Two things it needs from the box:

  • git, because Deployer's local_archive runs git archive in the runner's checkout. Without it, actions/checkout silently falls back to a tarball with no .git, and the deploy fails at deploy:update_code. Install it as root: apt-get install -y git.
  • The env key at /etc/blog-filament/env-key (ADR 0007).

The workflow installs Deployer to ~deploy/.local/bin/dep with install-deployer.sh, pinned and checksummed. It lives there rather than in a release so that rolling back never depends on GitHub:

sh
cd /var/www/blog-filament/current && ~/.local/bin/dep rollback production
~/.local/bin/dep releases production    # from the same directory: release numbers next to their tags