update documentation

.forgejo/workflows/deploy.yml

@@ -8,6 +8,9 @@ jobs:
   build-and-deploy:
     runs-on: docker
     steps:
+      - name: Install tools
+        run: apt-get update && apt-get install -y docker.io openssh-client
+
       - name: Checkout code
         uses: https://data.forgejo.org/actions/checkout@v4
 

documentation/deployment.md

@@ -225,9 +225,59 @@ Host git.lilastudy.com
 
 This allows standard git commands without specifying the port.
 
+## CI/CD Pipeline
+
+Automated build and deploy via Forgejo Actions. On every push to `main`, the pipeline builds ARM64 images natively on the VPS, pushes them to the Forgejo registry, and restarts the app containers.
+
+### Components
+
+- **Forgejo Actions** — enabled by default, workflow files in `.forgejo/workflows/`
+- **Forgejo Runner** — runs as a container (`lila-ci-runner`) on the VPS, uses the host's Docker socket to build images natively on ARM64
+- **Workflow file** — `.forgejo/workflows/deploy.yml`
+
+### Pipeline Steps
+
+1. Install Docker CLI and SSH client in the job container
+2. Checkout the repository
+3. Login to the Forgejo container registry
+4. Build API image (target: `runner`)
+5. Build Web image (target: `production`, with `VITE_API_URL` baked in)
+6. Push both images to `git.lilastudy.com`
+7. SSH into the VPS, pull new images, restart `api` and `web` containers, prune old images
+
+### Secrets (stored in Forgejo repo settings → Actions → Secrets)
+
+| Secret | Value |
+|---|---|
+| REGISTRY_USER | Forgejo username |
+| REGISTRY_PASSWORD | Forgejo password |
+| SSH_PRIVATE_KEY | Contents of `~/.ssh/ci-runner` on the VPS |
+| SSH_HOST | VPS IP address |
+| SSH_USER | `lila` |
+
+### Runner Configuration
+
+The runner config is at `/data/config.yml` inside the `lila-ci-runner` container. Key settings:
+
+- `docker_host: "automount"` — mounts the host Docker socket into job containers
+- `valid_volumes: ["/var/run/docker.sock"]` — allows the socket mount
+- `privileged: true` — required for Docker access from job containers
+- `options: "--group-add 989"` — adds the host's docker group (GID 989) to job containers
+
+The runner command must explicitly reference the config file:
+
+```yaml
+command: '/bin/sh -c "sleep 5; forgejo-runner -c /data/config.yml daemon"'
+```
+
+### Deploy Cycle
+
+Push to main → pipeline runs automatically (~2-5 min) → app is updated. No manual steps required.
+
+To manually trigger a re-run: go to the repo's Actions tab, click on the latest run, and use the re-run button.
+
 ## Known Issues and Future Work
 
-- **CI/CD**: Currently manual build-push-pull cycle. Plan: Forgejo Actions with a runner on the VPS building ARM images natively (eliminates QEMU cross-compilation)
 - **Backups**: Offsite backup storage (Hetzner Object Storage or similar) should be added
 - **Valkey**: Not in the production stack yet. Will be added when multiplayer requires session/room state
 - **Monitoring/logging**: No centralized logging or uptime monitoring configured

documentation/notes.md

@@ -28,6 +28,18 @@ laptop: verify if docker containers run on startup (they shouldnt)
 ### vps setup
 
 - monitoring and logging (eg via chrootkit or rkhunter, logwatch/monit => mails daily with summary)
+<<<<<<< HEAD
+- ~~keep the vps clean (e.g. old docker images/containers)~~ ✅ CI/CD pipeline runs `docker image prune -f` after deploy
+
+### ~~cd/ci pipeline~~ ✅ RESOLVED
+
+Forgejo Actions with runner on VPS, Forgejo built-in container registry. See `deployment.md`.
+
+### ~~postgres backups~~ ✅ RESOLVED
+
+Daily pg_dump cron job, 7-day retention, dev laptop auto-sync via rsync. See `deployment.md`.
+=======
+>>>>>>> dev
 
 ### try now option
 

documentation/spec.md

@@ -290,6 +290,17 @@ After completing a task: share the code, ask what to refactor and why. The LLM s
 
 ## 11. Post-MVP Ladder
 
+<<<<<<< HEAD
+| Phase             | What it adds                                                                    | Status |
+| ----------------- | ------------------------------------------------------------------------------- | ------ |
+| Auth              | Better Auth (Google + GitHub), embedded in Express API, user rows in DB         | ✅     |
+| Deployment        | Docker Compose, Caddy, Forgejo, CI/CD, Hetzner VPS                             | ✅     |
+| Hardening (partial) | CI/CD pipeline, DB backups                                                    | ✅     |
+| User Stats        | Games played, score history, profile page                                       | ❌     |
+| Multiplayer Lobby | Room creation, join by code, WebSocket connection                               | ❌     |
+| Multiplayer Game  | Simultaneous answers, server timer, live scores, winner screen                  | ❌     |
+| Hardening (rest)  | Rate limiting, error boundaries, monitoring, accessibility                      | ❌     |
+=======
 | Phase               | What it adds                                                            | Status |
 | ------------------- | ----------------------------------------------------------------------- | ------ |
 | Auth                | Better Auth (Google + GitHub), embedded in Express API, user rows in DB | ✅     |
@@ -299,6 +310,7 @@ After completing a task: share the code, ask what to refactor and why. The LLM s
 | Multiplayer Lobby   | Room creation, join by code, WebSocket connection                       | ❌     |
 | Multiplayer Game    | Simultaneous answers, server timer, live scores, winner screen          | ❌     |
 | Hardening (rest)    | Rate limiting, error boundaries, monitoring, accessibility              | ❌     |
+>>>>>>> dev
 
 ### Future Data Model Extensions (deferred, additive)