The pipeline logs in as gitea-workflow, a member of the www-data group. The test folder needs group write access (775, or 2775 with setgid); new folders get 755 by default, which made the first deploys fail. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
133 lines
9.0 KiB
Markdown
133 lines
9.0 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. 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, 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
|
|
- 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. |
|
|
| `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. |
|