The pipeline runs lint, format, tests, build, dependency audit and Lighthouse (mobile and desktop, Playwright Chromium on the arm64 runner) on every pull request, push to master and manual run. Pushes to master deploy to test automatically, and any branch can be deployed to test manually. Test is a Raspberry Pi with nginx next to the current WordPress site; the deploy refuses folders containing WordPress. Production deploys are manual and only from release/* branches, over FTP with TLS to the IIS webhost. The IIS web.config and both nginx configs are generated from the same security header list as the Vite servers, with a test that fails when the generated files drift. Adds .gitattributes for LF line endings and pins pnpm through packageManager. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.6 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 |
SSH user |
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. The global runner raspberry-pi-arm64 picks up runs-on: ubuntu-latest.
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.
- Create a separate folder, not inside the WordPress folder:
Every deploy empties this folder first. The pipeline refuses a folder with
sudo mkdir -p /var/www/html/andreaslop-test sudo chown <ssh-user> /var/www/html/andreaslop-testwp-config.phporwp-contentin it. - Copy
web/deploy/nginx/andreaslop-test.confto/etc/nginx/conf.d/andreaslop-test.conf. nginx loads everything inconf.d/automatically, so no symlink is needed. Adjustserver_nameandrootif needed.Aftersudo cp web/deploy/nginx/andreaslop-test.conf /etc/nginx/conf.d/andreaslop-test.confpnpm server-configchanges 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.
- The block answers only the test hostname, and never acts as
- Run
sudo nginx -t && sudo systemctl reload nginx. - 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
Hostheader 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 inconfig/serverConfig.ts. Change it there and runpnpm server-config, never in the generated file.
Then let certbot add TLS and the HTTP→HTTPS redirect. certbot edits this file on the proxy:sudo cp test.andreaslop.nl.proxy.conf /etc/nginx/conf.d/test.andreaslop.nl.conf sudo nginx -t && sudo systemctl reload nginxsudo 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.nlagain. Do not add the security headers orX-Robots-Tagon the proxy too. The hosting Pi already sets them, and setting them twice makes browsers see duplicate headers.
- The
- 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)
- In the control panel, create an FTP account for the website. Use its full username, prefix included, in
FTP_USERNAME. - 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.
- Set up the domain
andreaslop.nlin the package, but do not change the DNS yet (D12).
1.4 Later: SSH key instead of a password (recommended)
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
git switch -c feature/<name>frommaster, work, push.- Open a pull request. CI runs: lint, format, tests, build, audit and Lighthouse.
- Want to see it on test before merging? Go to Actions → Continuous Integration → Run workflow, pick your branch, tick Deploy to Test.
- Merge the PR.
masteris deployed to test automatically.
Release to production
- Cut a release branch from
master:git switch -c release/1.0 master, thengit push -u origin release/1.0. - Check it on test: run the workflow on
release/1.0with Deploy to Test. - Deploy: run the workflow on
release/1.0with Deploy to Production. The job only runs onrelease/*branches. - Afterwards, merge
release/1.0back intomaster(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 - 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)
- 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
hostsentry (<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
- the home page and a deep link (
- Remove the
hostsentry afterwards.
- Switch the DNS of
andreaslop.nl(andwww) to the new host, and make sure HTTPS is active. - Set
HEALTH_CHECK_URL_PRODUCTIONso every deploy is checked from then on. - Verify the live headers:
curl -sI https://andreaslop.nl/must show all five security headers.
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. |
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. |