Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/operations/deployment/deployment-instructions.md
T
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

155 lines
12 KiB
Markdown

# Deployment Instructions — frontend-shell
Pipeline: [`.gitea/workflows/continuous_integration.yaml`](../../../../../.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.
```bash
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`](../../../../../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.
```bash
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`](../../../../../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.
```bash
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:
```bash
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).
### 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:
```bash
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:
```bash
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. |