5.1 KiB
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:
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:
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:
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:
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:
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:
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.