# 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` | 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. 1. Create a separate folder, **not** inside the WordPress folder: ```bash sudo mkdir -p /var/www/html/andreaslop-test sudo chown /var/www/html/andreaslop-test ``` 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 - Remove the `hosts` entry afterwards. 2. Switch the DNS of `andreaslop.nl` (and `www`) to the new host, and make sure HTTPS is active. 3. Set `HEALTH_CHECK_URL_PRODUCTION` so every deploy is checked from then on. 4. 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. |