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

128 lines
5.1 KiB
Markdown

# 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.