Files
SluijsensandClaude Opus 5.5 0ddaaa2cb1
Continuous Integration / check (pull_request) Successful in 57s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 3m45s
Continuous Integration / deploy-production (pull_request) Skipped
Documents how the PC runner gets preference over the Pi
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 17:22:43 +02:00

12 KiB

Deployment Instructions — frontend-shell

Pipeline: .gitea/workflows/continuous_integration.yaml.

1. One-time setup

1.1 Gitea repository settings

In Gitea, under Repository → Settings → Actions:

Secrets (encrypted):

Name Value
PI_MAIN_ADDRESS Address of the Pi as reachable from the runner (same as in your other projects)
PI_MAIN_PORT SSH port
PI_MAIN_USERNAME gitea-workflow: the deploy user for pipelines, member of the www-data group (see 1.2)
PI_MAIN_PASSWORD SSH password (see 1.4 for switching to a key)
FTP_HOST Domain or A-record IP of the hosting space (control panel)
FTP_USERNAME FTP account including the FTP prefix
FTP_PASSWORD Password of that FTP account

Variables (not secret):

Name Example Required
DEPLOY_PATH_TEST /var/www/html/andreaslop-test yes
HEALTH_CHECK_URL_TEST https://test.andreaslop.nl/ no; without it the post-deploy check is skipped
HEALTH_CHECK_URL_PRODUCTION https://andreaslop.nl/ no; set it only once the DNS points to the new host
FTP_REMOTE_DIR wwwroot no; default wwwroot

Check that Actions is enabled for the repository. Two global runners, each job image gitea/runner-images:ubuntu-latest. A job runs on a runner that has all its runs-on labels.

Runner Labels Always on Runs
raspberry-pi-arm64 (systemd service gitea-runner, config /etc/gitea-runner/config.yaml) global, linux, arm64, podman, raspberry-pi, plus ubuntu-latest and linux-arm64 for older workflows yes everything
bryan-desktop-podman (Podman machine on the owner's PC, C:\Users\Bryan\gitea-runner\) global, linux, x64, podman, bryan-desktop no check and lighthouse when it is free

check and lighthouse use runs-on: linux, the deploys runs-on: raspberry-pi. deploy-test is listed above lighthouse in the workflow: Gitea hands out waiting jobs in that order, so a single free runner deploys first, while two runners deploy and run Lighthouse at the same time.

Gitea has no runner priority: a job goes to the first runner that asks for work and has all its labels, and a runner asks again right after finishing a job. To let the PC take check and lighthouse when it is on, the PC asks every second and the Pi every 10 seconds:

Runner Setting under runner:
PC (C:\Users\Bryan\gitea-runner\config.yaml) fetch_interval: 1s and fetch_interval_max: 1s (no slowing down while idle)
Pi (/etc/gitea-runner/config.yaml) fetch_interval: 10s; restart with sudo systemctl restart gitea-runner only while it runs no job

This is a strong preference, not a guarantee: a busy PC leaves the job to the Pi, and with the PC off the Pi starts a run at most 10 seconds later.

Notes for the PC runner: its job containers share the WSL kernel, so the runner mounts an empty /.dockerenv (otherwise is-wsl in chrome-launcher treats the container as WSL and Lighthouse fails). Container actions (uses: of a Docker action) do not work on Podman; that is one reason deploys stay on the Pi.

1.2 Test server (Raspberry Pi with nginx)

The current WordPress site runs on the same Pi. The test site gets its own folder and its own nginx block, and touches nothing of WordPress.

  1. Create a separate folder, not inside the WordPress folder, and give the www-data group write access.

    The pipeline logs in as gitea-workflow, a member of the www-data group. Group write access on the folder is enough; gitea-workflow does not need to own it. The folder may be created by another user, for example webadmin (also in www-data) via FileZilla.

    sudo mkdir -p /var/www/html/andreaslop-test
    sudo chgrp www-data /var/www/html/andreaslop-test
    sudo chmod 2775 /var/www/html/andreaslop-test
    
    • 775 is required. New folders get 755 by default, also when created with FileZilla or mkdir. With 755 the group may only read, and the deploy fails with Permission denied. Check it with ls -ld /var/www/html/andreaslop-test: it must show drwxrwxr-x (or drwxrwsr-x with the 2).
    • The 2 (setgid) is optional but recommended. New files and folders in the test folder then also get group www-data, so webadmin and gitea-workflow can keep managing each other's files.
    • On the Pi /var/www/html is a symlink to /mnt/storage1/www/html (external disk). Rights on the symlink itself are ignored; the folder it points to counts. The commands above work through the symlink.

    Every deploy empties this folder first. The pipeline refuses a folder with wp-config.php or wp-content in it.

  2. Copy web/deploy/nginx/andreaslop-test.conf to /etc/nginx/conf.d/andreaslop-test.conf. nginx loads everything in conf.d/ automatically, so no symlink is needed. Adjust server_name and root if needed.

    sudo cp web/deploy/nginx/andreaslop-test.conf /etc/nginx/conf.d/andreaslop-test.conf
    

    After pnpm server-config changes the file, copy it again (manual step; see "Test vs Production" in the deployment plan).

    • The block answers only the test hostname, and never acts as default_server, so WordPress keeps getting its own requests.
    • Do not change the WordPress server block.
  3. Run sudo nginx -t && sudo systemctl reload nginx.

  4. On the reverse-proxy Pi, install the HTTP-only proxy config web/deploy/nginx/test.andreaslop.nl.proxy.conf. It forwards the test hostname to the hosting Pi.

    • The Host header is required, and the file sets it. The hosting Pi uses it to choose between the WordPress block and the test block; without it the request lands on the default block (WordPress).
    • The hosting Pi's address (192.168.1.103) is set in config/serverConfig.ts. Change it there and run pnpm server-config, never in the generated file.
    sudo cp test.andreaslop.nl.proxy.conf /etc/nginx/conf.d/test.andreaslop.nl.conf
    sudo nginx -t && sudo systemctl reload nginx
    

    Then let certbot add TLS and the HTTP→HTTPS redirect. certbot edits this file on the proxy:

    sudo certbot --nginx -d test.andreaslop.nl
    
    • Only copy the file once. Copying it again overwrites certbot's HTTPS changes. If the repository version ever changes, copy it and run certbot --nginx -d test.andreaslop.nl again. Do not add the security headers or X-Robots-Tag on the proxy too. The hosting Pi already sets them, and setting them twice makes browsers see duplicate headers.
  5. Create a DNS record for the test hostname that points to your proxy.

The folder is empty until the first deploy. Run a deploy before testing.

1.3 Production (MijnHostingPartner)

  1. In the control panel, create an FTP account for the website. Use its full username, prefix included, in FTP_USERNAME.
  2. Check that TLS is available for FTP. If it isn't, open a ticket (per the hoster's knowledge base); the pipeline refuses plain FTP.
  3. Set up the domain andreaslop.nl in the package, but do not change the DNS yet (D12).

Create a deploy key, put the public key in ~/.ssh/authorized_keys on the Pi, and store the private key as the secret PI_MAIN_SSH_KEY. In the deploy-test job, replace sshpass -e with ssh -i. This is the same change as in your other projects.

1.5 Line endings (once, after pulling this change)

.gitattributes makes Git use LF. Refresh your working copy once:

git rm --cached -r -q . && git reset --hard

Warning: this throws away uncommitted changes. Commit or stash first.

2. Day to day

Feature work

  1. git switch -c feature/<name> from master, work, push.
  2. Open a pull request. CI runs: lint, format, tests, build, audit and Lighthouse.
  3. Want to see it on test before merging? Go to Actions → Continuous Integration → Run workflow, pick your branch, tick Deploy to Test.
  4. Merge the PR. master is deployed to test automatically.

Release to production

  1. Cut a release branch from master: git switch -c release/1.0 master, then git push -u origin release/1.0.
  2. Check it on test: run the workflow on release/1.0 with Deploy to Test.
  3. Deploy: run the workflow on release/1.0 with Deploy to Production. The job only runs on release/* branches.
  4. Afterwards, merge release/1.0 back into master (PR) and tag the merge commit:
    git switch master && git pull
    git tag -a v1.0.0 -m "Release 1.0.0" && git push origin v1.0.0
    
  5. A fix on a release goes to the release branch first, and is deployed and merged back the same way (tag v1.0.1).

Go-live (once)

  1. Dress rehearsal on the production host. This is the only place IIS and FTPS are tested; test runs nginx (see "Test vs Production" in the deployment plan).
    • Run a production deploy.
    • Without changing DNS, open the new host via a temporary hosts entry (<A-record IP> andreaslop.nl) or the hoster's preview URL.
    • Check:
      • the home page and a deep link (/portfolio)
      • an unknown URL (the 404 page)
      • the five security headers (curl -sI)
      • that HTTP redirects to HTTPS
      • that www.andreaslop.nl (also add it to the hosts entry) redirects with 301 to https://andreaslop.nl/ in one step, path included
    • Remove the hosts entry afterwards.
  2. Privacy statement first (blocking). The privacy statement page must mention Umami (anonymous, cookieless, self-hosted in the Netherlands) and Sentry (error reports without IP address or personal data, EU region). Do not switch the DNS before it does.
  3. Switch the DNS of andreaslop.nl and www to the new host, and make sure HTTPS is active for both (the certificate must cover www, otherwise the redirect shows a certificate error first).
  4. Set HEALTH_CHECK_URL_PRODUCTION so every deploy is checked from then on.
  5. Verify the live headers: curl -sI https://andreaslop.nl/ must show all five security headers.
  6. Add the UptimeRobot deep-link monitor for https://andreaslop.nl/portfolio (monitoring-setup §3).
  7. Check the monitoring on production: a test error in the console arrives in Sentry under production, and a visit shows in Umami's production website.

3. If something fails

Symptom Likely cause Fix
Install Chromium fails Playwright cannot install its dependencies in the runner image Look at the log for the missing package. As a fallback, run Lighthouse locally (pnpm lighthouse) and make the CI job optional; report it so we can fix it properly.
Lighthouse: "Chrome could not be started" Sandbox LIGHTHOUSE_CHROME_FLAGS must contain --no-sandbox (already set).
Format fails only in CI Line endings See 1.5.
sshpass: Permission denied Wrong secret, or special characters Secrets go via env: (already so); check the values.
mkdir: cannot create directory or scp: dest open …: Permission denied The test folder does not exist, or the www-data group may not write to it (755 instead of 775) See 1.2: chgrp www-data and chmod 2775 on the test folder.
lftp: certificate verification failed Hostname does not match the hoster's certificate Use the hostname from the control panel in FTP_HOST, not the IP.
Health check fails, page is 404 on deep links SPA fallback missing Production: web.config not uploaded or URL Rewrite off. Test: nginx config not active.