From 7938a1620bfe32722f89761dd8f5cead1e28c3f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joakim=20M=C3=B6rling?= <jcamorling@gmail.com>
Date: Wed, 20 May 2026 11:28:38 +0200
Subject: [PATCH] docs: add production deployment guide to README

Adds a comprehensive 'Production Deployment' section covering:

- One-time server setup (Forgejo secrets, DNS, SSL certbot, nginx config)
- How to trigger a deploy from the Forgejo Actions UI
- What the deploy pipeline does step-by-step
- Architecture diagram showing how nginx, frontend, backend, and postgres
  containers interact on the production server
- Rollback procedure using git tags and docker compose

This documents the deploy.yml workflow and bilhej.nginx.conf added in
the previous commit.
---
 README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/README.md b/README.md
index 7f4c5c0..81f8e5e 100644
--- a/README.md
+++ b/README.md
@@ -165,6 +165,113 @@ bilhej/
 
 ---
 
+## Production Deployment
+
+Deployments are fully automated via Forgejo Actions. The pipeline builds production Docker images and starts them on the server.
+
+### One-time Setup
+
+Before the first deploy, complete these steps on the production server (`srvr.nu`):
+
+1. **Add Forgejo Actions Secrets**
+
+   Go to **Forgejo → Repository Settings → Actions → Secrets** and add:
+
+   | Secret | Description |
+   |--------|-------------|
+   | `POSTGRES_DB` | Database name (e.g., `bilhej`) |
+   | `POSTGRES_USER` | Database user |
+   | `POSTGRES_PASSWORD` | Strong database password |
+   | `JWT_SECRET` | `openssl rand -hex 32` |
+   | `STRIPE_SECRET_KEY` | Stripe secret key |
+   | `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret |
+   | `STRIPE_PRICE_ID` | Stripe price ID for single letter |
+   | `SWISH_NUMBER` | Swish phone number for payment instructions |
+
+2. **Point DNS**
+
+   Set `bilhej.se` (and `www.bilhej.se`) A record to the server's public IP.
+
+3. **Obtain SSL Certificate**
+
+   Run certbot in the nginx container:
+
+   ```bash
+   docker exec certbot certbot certonly \
+     --webroot -w /var/www/certbot \
+     -d bilhej.se -d www.bilhej.se
+   ```
+
+4. **Add Nginx Config**
+
+   Copy the Bilhej server block into the nginx container:
+
+   ```bash
+   docker cp docker/bilhej.nginx.conf nginx:/etc/nginx/conf.d/bilhej.conf
+   docker exec nginx nginx -s reload
+   ```
+
+### Deploy
+
+1. Go to **Actions → Deploy to Production** in Forgejo.
+2. Click **Run workflow**.
+3. Enter a version tag (e.g., `v0.1.0`).
+4. Click **Run workflow**.
+
+### What Happens
+
+| Step | Action |
+|------|--------|
+| Tag | Git tag `v0.1.0` is created and pushed |
+| Build | Production backend JAR and frontend bundle are built |
+| Images | Multi-stage Docker images are built locally on the server |
+| Start | `docker compose -f docker-compose.prod.yml up -d` |
+| Verify | Health checks confirm backend API and frontend are responding |
+
+### Architecture on Server
+
+```
+  User
+   │
+   │ https://bilhej.se
+   ▼
+┌─────────────────────────────────────┐
+│  nginx (srvr.nu)                    │
+│  SSL termination (Let's Encrypt)    │
+│  proxy_pass → bilhej-frontend-prod  │
+└─────────────┬───────────────────────┘
+              │ Docker 'web' network
+┌─────────────▼───────────────────────┐
+│  bilhej-frontend-prod (nginx)       │
+│  :80                                │
+│  /api/* → bilhej-backend-prod:8080  │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│  bilhej-backend-prod (Spring Boot)  │
+│  :8080                              │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│  bilhej-postgres-prod (PostgreSQL)  │
+│  :5432                              │
+└─────────────────────────────────────┘
+```
+
+### Rollback
+
+To rollback to a previous version:
+
+```bash
+# On srvr.nu
+cd /path/to/bilhej/repo
+git fetch --tags
+git checkout v0.1.0   # or any previous tag
+docker compose -f docker-compose.prod.yml up --build -d
+```
+
+---
+
 ## Development
 
 ### All-in-one (from repo root)