add deploy actions

.gitea/workflows/SETUP.md

@@ -0,0 +1,131 @@
+# Gitea Actions — Setup Guide
+
+## Prerequisites
+
+You need a **Gitea runner** registered to your repo or organisation.
+If you don't have one yet:
+
+```bash
+# On your droplet (or any always-on machine)
+# Download the runner binary from your Gitea instance:
+# https://git.etcprs.app/-/admin/runners  (site admin)
+# or https://git.etcprs.app/<org>/runners (org level)
+
+# Install and register
+./gitea-runner register \
+  --instance https://git.etcprs.app \
+  --token    LSD3GDaXRaU9TUxtrlm8M3hOF72KFipIYchUpqda \
+  --name     "droplet-runner" \
+  --labels   "ubuntu-latest"
+```
+
+---
+
+## 1. Generate a deploy key
+
+Run this **on your local machine** (not the server):
+
+```bash
+ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/deploy_key -N ""
+```
+
+This creates two files:
+- `~/.ssh/deploy_key`      — private key (goes into Gitea secret)
+- `~/.ssh/deploy_key.pub`  — public key (goes onto the server)
+
+---
+
+## 2. Add the public key to the server
+
+```bash
+# Copy the public key to the droplet
+ssh-copy-id -i ~/.ssh/deploy_key.pub root@your-droplet-ip
+
+# Or manually:
+cat ~/.ssh/deploy_key.pub | ssh root@your-droplet-ip \
+  "cat >> ~/.ssh/authorized_keys"
+```
+
+Test it works:
+
+```bash
+ssh -i ~/.ssh/deploy_key root@your-droplet-ip "echo connected"
+```
+
+---
+
+## 3. Add secrets to Gitea
+
+Go to your repo → **Settings → Secrets → Actions** and add:
+
+| Secret name      | Value                                          |
+|------------------|------------------------------------------------|
+| `DEPLOY_HOST`    | Your droplet IP or hostname                    |
+| `DEPLOY_USER`    | `root`                                         |
+| `DEPLOY_SSH_KEY` | Contents of `~/.ssh/deploy_key` (private key)  |
+| `DEPLOY_PORT`    | `22`                                           |
+
+To get the private key contents:
+
+```bash
+cat ~/.ssh/deploy_key
+```
+
+Copy the entire output including the `-----BEGIN...-----` and `-----END...-----` lines.
+
+---
+
+## 4. Enable Actions on your repo
+
+In Gitea: **Settings → Repository → Enable Repository Actions** ✓
+
+---
+
+## 5. How it works
+
+### On any branch push or PR → `ci.yml` runs:
+1. Install dependencies (`npm ci`)
+2. JS syntax check (`node --check` on all `.js` files)
+3. Svelte component check (`svelte-check`)
+4. Full build (`npm run build`)
+
+If any step fails, the push is marked as failed. No deploy occurs.
+
+### On push to `main` → `deploy.yml` runs:
+1. All CI steps above (build must pass first)
+2. SSH into the droplet
+3. `git pull`
+4. `npm install`
+5. `npm run build`
+6. `chown` to fix file ownership
+7. `pm2 reload etc-prs` (zero-downtime reload)
+
+---
+
+## 6. Monitoring
+
+View workflow runs at:
+`https://git.etcprs.app/<your-repo>/actions`
+
+---
+
+## Troubleshooting
+
+**"Host key verification failed"**
+Add your droplet to known hosts on the runner, or add `StrictHostKeyChecking no`
+to the SSH action config (already handled by `appleboy/ssh-action`).
+
+**"pm2: command not found"**
+PM2 is installed globally but the SSH session may not have it in PATH. Fix:
+
+```bash
+# On the server, find where pm2 is
+which pm2   # e.g. /usr/local/bin/pm2
+
+# If needed, symlink it to /usr/bin
+ln -s /usr/local/bin/pm2 /usr/bin/pm2
+```
+
+**Build fails with missing env vars**
+The CI workflow passes dummy env vars — this is intentional. The real vars
+are in the PM2 ecosystem config on the server and are never needed at build time.