# Gitea production deployment `.gitea/workflows/deploy-control-plane.yml` runs for a pushed `vX.X.X` tag. It runs backend and frontend checks in isolated Docker build stages, builds immutable backend, frontend, and Grafana images, pushes them to the configured container registry, copies only the Compose definitions and the deployment helper over SSH, and waits for all enabled service health checks. The production host keeps its own `.env`, `secrets/`, PostgreSQL volume, and reverse-proxy configuration. The workflow never copies those values from CI. ## Gitea configuration Keep these existing instance-level values: | Kind | Name | Purpose | | --- | --- | --- | | Variable | `REGISTRY_HOST` | Registry hostname with optional port, without `https://` | | Secret | `REGISTRY_USERNAME` | Registry login/user name | | Secret | `REGISTRY_PASSWORD` | Gitea PAT with `write:package` access (which includes read) | | Secret | `RELEASE_TOKEN` | Used by the separate agent release workflow | Add the following Actions variables: | Name | Example | Purpose | | --- | --- | --- | | `DEPLOY_HOST` | `control.example.net` | SSH hostname or IPv4 address | | `DEPLOY_PORT` | `22` | SSH port; an empty value defaults to 22 | | `DEPLOY_USER` | `vps-deploy` | Dedicated deployment user | | `DEPLOY_PATH` | `/opt/vps-control` | Absolute deployment directory; an existing clone's `control-plane` directory is also valid | | `DEPLOY_PROFILES` | `observability` | Empty for core services, or `observability` to run Grafana | Add these Actions secrets: | Name | Purpose | | --- | --- | | `DEPLOY_SSH_KEY` | Complete unencrypted OpenSSH private key for the deployment user | | `DEPLOY_SSH_KNOWN_HOSTS` | Pinned OpenSSH known-hosts line for the production server | The workflow asks Gitea for `contents: read` and `packages: write`. Repository or owner Actions settings must not clamp package access below write. The registry account must be allowed to push and pull packages for the repository owner. Protect `v*` tags so they cannot be moved to another commit after publication. The explicit PAT is intentional: Gitea documents that automatic job-token authorization for publishing OCI packages is not implemented yet. ## Prepare the production server Install Docker Engine, the current Docker Compose v2 plugin, `flock` (normally provided by `util-linux`), and an SSH server. The deployment user needs access to Docker and must own the deployment directory. Membership in the Docker group is effectively root-equivalent, so use a dedicated host and key. Example for Debian or Ubuntu after Docker is installed: ```bash sudo useradd --create-home --shell /bin/bash vps-deploy sudo usermod --append --groups docker vps-deploy sudo install -d -o vps-deploy -g vps-deploy -m 0700 /opt/vps-control ``` Create an SSH key on a trusted administrator machine and install only its public half on the server: ```bash ssh-keygen -t ed25519 -f ./gitea-vps-control-deploy -C gitea-vps-control-deploy ssh-copy-id -i ./gitea-vps-control-deploy.pub vps-deploy@control.example.net ``` Put the private-key file content into `DEPLOY_SSH_KEY`. Obtain the server host key, verify its fingerprint through a separate trusted channel, and then put the resulting complete line into `DEPLOY_SSH_KNOWN_HOSTS`: ```bash ssh-keyscan -p 22 control.example.net ``` On the production server, create `/opt/vps-control/.env` and the secret files before the first deployment. Their format is described in `control-plane/README.md`: ```bash cd /opt/vps-control mkdir -m 0700 secrets openssl rand -hex 32 > secrets/db_password openssl rand -base64 24 > secrets/admin_password openssl rand -hex 32 > secrets/integration_token openssl rand -base64 24 > secrets/grafana_admin_password openssl rand -hex 32 > secrets/grafana_secret_key install -m 0600 /secure/source/control-plane.token secrets/agent_token chmod 0600 secrets/* ``` Create `.env` from `control-plane/.env.example` and set production bindings, cookie security, retention, and optional bootstrap values. The pipeline refuses to deploy when `.env` or `secrets/` is absent. If Gitea uses a private CA, install that CA in Docker's trust store on both the runner and production host. Do not disable registry TLS verification. ## Release and rollback behavior Commit the workflow and deployment files before creating the tag: ```bash git tag -a v0.1.0 -m "VPS Control v0.1.0" git push origin main git push origin v0.1.0 ``` Images use immutable version tags: ```text REGISTRY_HOST/owner/repository-backend:v0.1.0 REGISTRY_HOST/owner/repository-frontend:v0.1.0 REGISTRY_HOST/owner/repository-grafana:v0.1.0 ``` The remote helper serializes deployments with `flock`, validates the rendered Compose configuration, pulls images, and runs `docker compose up --wait`. If a health check fails and a previous `.release.env` exists, it restores the prior image set and tries to start it again. Registry credentials are kept in a temporary Docker config and removed after the SSH session. Image rollback does not roll back a database schema. Keep tested PostgreSQL backups before releases that change migrations; forward-only migration rollback requires restoring the corresponding database backup.