add cicd
This commit is contained in:
127
docs/gitea-deploy.md
Normal file
127
docs/gitea-deploy.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# 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://` |
|
||||
| Variable | `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.
|
||||
71
docs/gitea-release.md
Normal file
71
docs/gitea-release.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Gitea release pipeline
|
||||
|
||||
The workflow in `.gitea/workflows/release-agent.yml` runs only for pushed tags
|
||||
matching `v*.*.*`. It then applies a stricter `vX.X.X` check, verifies that the
|
||||
tag matches the version in `agent/Cargo.toml`, builds static Linux binaries for
|
||||
amd64 and arm64, creates `SHA256SUMS`, and publishes all three files in a Gitea
|
||||
release.
|
||||
|
||||
## Runner requirements
|
||||
|
||||
Register an amd64 Gitea Actions runner whose `ubuntu-latest` label resolves to a
|
||||
Linux environment with:
|
||||
|
||||
- `bash`, `curl`, `jq`, `file`, `sha256sum`, Git, and CA certificates;
|
||||
- Rustup and Cargo;
|
||||
- Docker with permission for the runner user to access its daemon;
|
||||
- outbound access to the Rust registries and the container registry used by
|
||||
`cross`.
|
||||
|
||||
The job installs the pinned Rust 1.85.1 toolchain and `cross` 0.2.5. `cross`
|
||||
uses Docker to build both musl targets; no amd64 or arm64 build host is required.
|
||||
Do not expose the Docker daemon over an unauthenticated TCP socket.
|
||||
|
||||
The simplest setup is a dedicated runner VM with an `ubuntu-latest:host` label.
|
||||
If jobs run inside a container instead, that container needs the Docker CLI and
|
||||
controlled access to the host Docker socket. A runner that executes untrusted
|
||||
repositories must not share this Docker access.
|
||||
|
||||
## Secrets, variables, and permissions
|
||||
|
||||
Configure this instance- or repository-level Actions secret:
|
||||
|
||||
- `RELEASE_TOKEN` (required): a Gitea access token for a dedicated automation
|
||||
account with write access to releases in this repository. Store it as a
|
||||
**secret**, not as a variable.
|
||||
|
||||
The workflow requests `contents: read` and `releases: write`. The token owner
|
||||
must also be allowed to read the repository and create releases. Protect the
|
||||
release tags so only trusted maintainers or automation can push them.
|
||||
|
||||
No custom Actions variables are required. Existing `REGISTRY_HOST`,
|
||||
`REGISTRY_USERNAME`, and `REGISTRY_PASSWORD` values are deliberately unused:
|
||||
this pipeline publishes release assets and does not push a container image.
|
||||
Gitea supplies `GITHUB_API_URL`, `GITHUB_REPOSITORY`, and `GITHUB_REF_NAME` to
|
||||
the job automatically.
|
||||
|
||||
## Publishing a release
|
||||
|
||||
First update `agent/Cargo.toml` and commit the change. Then create and push the
|
||||
matching annotated tag:
|
||||
|
||||
```bash
|
||||
git tag -a v0.1.0 -m "VPS Agent v0.1.0"
|
||||
git push origin v0.1.0
|
||||
```
|
||||
|
||||
After the job succeeds, the `v0.1.0` release contains:
|
||||
|
||||
- `vps-agent-linux-amd64`
|
||||
- `vps-agent-linux-arm64`
|
||||
- `SHA256SUMS`
|
||||
|
||||
The publisher refuses to overwrite an existing release. If a job fails while
|
||||
uploading assets, it removes the incomplete release so that the same tag can be
|
||||
rerun safely. It never deletes the Git tag.
|
||||
|
||||
Before installation, verify the downloaded binary:
|
||||
|
||||
```bash
|
||||
sha256sum --check SHA256SUMS
|
||||
```
|
||||
Reference in New Issue
Block a user