128 lines
5.1 KiB
Markdown
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.
|