# 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/` 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 (` 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. |