Files
vps-control/docs/gitea-deploy.md
2026-09-24 23:30:13 +03:00

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.