# Deploying FlatRender (Gitea CI/CD → server)

Push to **Gitea** triggers `.gitea/workflows/ci-cd.yml`: a frontend `tsc` check, then a
self-hosted `deploy` job that builds the whole compose stack and brings it up behind
Caddy (Let's Encrypt HTTPS). GitHub (`origin`) stays a backup and never deploys.

Stack: gateway · identity · content · studio (.NET/Go) · file · render · notification
(Go) · Next.js frontend · Postgres · MinIO · Caddy. All package installs route through
`mirror.soroushasadi.com` (Nexus).

## One-time setup (do these BEFORE the first `git push gitea master`)

1. **DNS** — point three A-records at the server:
   `DOMAIN`, `API_DOMAIN`, `STORAGE_DOMAIN` (e.g. flatrender.ir / api.flatrender.ir / storage.flatrender.ir).
2. **Firewall** — `ufw allow 22,80,443/tcp`. Everything else binds to `127.0.0.1`
   (via `HOST_BIND=127.0.0.1` in the env), so only Caddy faces the internet.
3. **Gitea Actions** — enabled for this repo, and an `act_runner` is registered with the
   `self-hosted:host` label (the standard server already has this).
4. **ENV_FILE secret** — at `…/soroushdes/flatrender/settings/secrets`, create `ENV_FILE`
   with the filled-in contents of [`ENV_FILE.production.example`](./ENV_FILE.production.example)
   (generate each secret with `openssl rand -hex 32`).
5. **Server prerequisites** (already true on the Gitea+Nexus box): Docker + compose v2,
   `/etc/docker/daemon.json` has `{"registry-mirrors":["https://mirror.soroushasadi.com"]}`.

## Go live

```bash
git push gitea master      # triggers CI + deploy
```

Watch: `https://git.soroushasadi.com/soroushdes/flatrender/actions`.
First run is the slowest (cold Nexus cache + all images build, ~15–25 min). Caddy issues
TLS certs on first boot. Then visit `https://DOMAIN`.

## First-run notes

- **Migrations** auto-run once via `scripts/init-db.sh` when the Postgres volume is first
  created. Later schema changes are applied manually with `psql` (the data volume persists).
- **Admin seed** — create the first admin per the project's identity seed flow, then log in
  at `https://DOMAIN` → admin.
- **Rendering** — there is no After Effects node on the server, so `RENDER_DEV_WORKER=false`.
  Disable rendering in **Admin → فارم رندر → موتور رندر** so users see an "unavailable" notice
  instead of jobs that never finish. (Point real render nodes at the server later.)
- **MinIO public URLs** — verify an uploaded image and a render download resolve over
  `https://STORAGE_DOMAIN`. If not, recheck `MINIO_HOST_ENDPOINT` / `MINIO_HOST_USE_SSL` /
  `NEXT_PUBLIC_MINIO_URL` in the secret and redeploy.

## Redeploy / rotate secrets

Edit `ENV_FILE` in Gitea (or push any commit) → the deploy job re-runs. It backs up the DB
to `/opt/flatrender-backups/` before each deploy and never runs `docker compose down -v`.
Changing a `NEXT_PUBLIC_*` value only takes effect after the redeploy (baked at build time).