chg: pkg: implement CD script to Gitea and add docs to the process #4

README.md

@@ -154,6 +154,7 @@ services:
   mail:
     image: mailhog/mailhog:latest
     ports:
+      - "1025:1025"
       - "8025:8025"
 ```
 
@@ -174,6 +175,111 @@ Open the web UI at **http://localhost:8025** to inspect them.
 
 ---
 
+## Deploying to production
+
+Releases are automated via Gitea Actions. Pushing a tag that starts with `v` (e.g. `v2026.01`) triggers the workflow at `.gitea/workflows/deploy.yml`.
+The job runs on a **self-hosted runner** installed on the production server — the server only needs an outbound connection to Gitea, no open SSH port required.
+The `app` image is rebuilt with the new code; the database and storage containers are untouched so all data is preserved.
+
+### Gitea repository variables and secrets
+
+**Variable** (plaintext, editable — **Repository → Settings → Variables**):
+
+| Variable | Value |
+|---|---|
+| `PROD_APP_DIR` | Absolute path on the server (e.g. `/var/www/mineseeker`) |
+
+**Secret** (encrypted, write-only — **Repository → Settings → Secrets**):
+
+| Secret | Value |
+|---|---|
+| `PROD_ENV_FILE` | Full content of the production `.env` file (see below) |
+
+The workflow writes `PROD_ENV_FILE` to `.env` on every deploy, so you never need to manage the file on the server manually. To update a credential, overwrite the secret in Gitea and push a new tag.
+
+#### `PROD_ENV_FILE` contents
+
+Paste the filled-in `.env` file as the secret value:
+
+```dotenv
+APP_ENV=prod
+APP_SECRET="<openssl rand -hex 32>"
+
+DATABASE_URL=postgresql://POSTGRES_USER:POSTGRES_PASSWORD@db:5432/POSTGRES_DB?serverVersion=18&charset=utf8
+
+POSTGRES_USER=mineseeker
+POSTGRES_PASSWORD="<strong password>"
+POSTGRES_DB=mineseeker
+POSTGRES_VERSION=18
+
+MINIO_ROOT_USER=mineseeker
+MINIO_ROOT_PASSWORD="<strong password>"
+MINIO_ENDPOINT=http://minio:9000
+MINIO_PUBLIC_URL=https://minio.mineseeker.hu
+
+MAILER_DSN=smtp://mail:25?verify_peer=0
+MAIL_DOMAIN=mineseeker.hu
+
+RECAPTCHA_SITE_KEY="<your reCAPTCHA v3 site key>"
+RECAPTCHA_SECRET_KEY="<your reCAPTCHA v3 secret key>"
+
+MERCURE_URL=https://mineseeker.hu/.well-known/mercure
+MERCURE_PUBLIC_URL=https://mineseeker.hu/.well-known/mercure
+MERCURE_JWT_SECRET="<generated by make mercure-jwt>"
+MERCURE_JWT_TOKEN="<generated by make mercure-jwt>"
+MERCURE_SUBSCRIBER_JWT="<generated by make mercure-jwt>"
+
+APP_PUBLIC_HOSTNAME=mineseeker.hu
+WEBAUTHN_RP_ID=mineseeker.hu
+WEBAUTHN_ORIGIN=https://mineseeker.hu
+```
+
+### Production server: one-time setup
+
+The server needs Docker, Git, and a self-hosted `act_runner` registered against the Gitea repository. Bun and Composer run inside the multi-stage Dockerfile, so they are not needed on the server.
+
+#### 1. Clone the repository
+
+```bash
+git clone https://gitea.mineseeker.hu/youruser/mineseeker.git /var/www/mineseeker
+```
+
+#### 2. Generate Mercure JWT tokens (run once locally)
+
+```bash
+composer install   # only needed for this step
+make mercure-jwt
+```
+
+Copy the three printed values into the `PROD_ENV_FILE` secret.
+
+#### 5. First deploy
+
+Trigger it by pushing the first tag:
+
+```bash
+git tag v2026.01
+git push origin v2026.01
+```
+
+This writes `.env`, builds the Docker image, starts all services, runs migrations, and initialises the MinIO buckets automatically via `minio_init`.
+
+#### 6. Verify
+
+```bash
+docker compose ps        # all services should be healthy/running
+docker compose logs app  # look for "Starting FrankenPHP"
+```
+
+### Releasing
+
+```bash
+git tag v2026.01
+git push origin v2026.01
+```
+
+---
+
 ## License
 
 LGPL-3.0 — see [LICENSE](LICENSE) for details.