Files
akyldash/docs/operations/DEPLOYMENT.md
agent ba669fad34
CI / tests-and-images (pull_request) Successful in 2m5s
Runner smoke test / runner-smoke (pull_request) Successful in 2s
Merge remote-tracking branch 'origin/main' into feature/release-manifest-contract
# Conflicts:
#	CHANGELOG.md
2026-10-20 00:18:34 +03:00

7.2 KiB

Deployment

Current status

Production deployment is not enabled or tested on the VPS. The owner completed the root bootstrap: Docker/Compose are active and target directories exist. The codex account cannot access the Docker socket. No root-owned checkout or restricted helpers are installed; protected env/secret metadata and Docker container/volume state remain unverified because they require root. The unprivileged audit sees no listener on 80, 443, or 1500; Cloudflare still returns 521. Do not deploy until the owner has reviewed root-only host state, supplied protected configuration and the approved corpus/index, and backup/restore have been tested.

First host preparation

  1. The initial root bootstrap is complete. After reviewing and merging the infrastructure PR, the owner must install that approved main checkout at /opt/akyldash/current (the path was absent during the unprivileged audit):

    sudo git clone --branch main --single-branch https://git.vakanaut.ru/admin/akyldash.git /opt/akyldash/current
    

    The checkout is root-owned by default. Then run sudo bash /opt/akyldash/current/infra/bootstrap/audit-host.sh. This read-only audit reports Docker state, protected-file metadata, UFW rules, listeners, and ISPmanager without printing secret contents. Resolve any existing containers, volumes, or data before proceeding; do not overwrite or delete them.

  2. After confirming the existing env and secret do not exist and reviewing the tracked defaults, run sudo bash /opt/akyldash/current/infra/deploy/prepare-production-config.sh. It creates /etc/akyldash/production.env from the tracked example and generates /etc/akyldash/review_secret; both are root-owned mode 0600. It refuses to overwrite either file and does not start services or create volumes. Review DATA_ROOT and follow the corpus inventory and handoff gates before placing the approved normalized corpus there.

  3. After reviewing the root-owned checkout and audit output, run sudo bash /opt/akyldash/current/infra/deploy/install-helper.sh. It installs the backup reader, read-only verifier, akyldash-compose config|status, and rollback helper with exact sudoers command rules. The Compose helper has no start/stop/build operation and grants no direct Docker access. Actual deployments remain owner-run through the documented Compose commands.

  4. Confirm DNS points through Cloudflare to this origin. The owner reports UFW already allows TCP 80 and 443; read and document the full rules before any firewall decision. TCP 1500 is allowed by owner report but has no observed listener and no ISPmanager package/service was found; the owner must identify its purpose. Do not change UFW as part of this procedure. The Compose Caddy service obtains and renews HTTPS certificates automatically; Cloudflare Full (strict) still needs end-to-end verification.

  5. For a clean first deployment, skip backup only when Compose confirms there are no containers and all persistent mounts are empty. If any data exists, create and verify a backup before starting a new version. For a preloaded corpus with absent named volumes, use --initial-deployment; it is limited to a container-free host whose DATA_ROOT contains only minjust-normalized/. Normal backups reject absent volumes. An uncertain or partial state stops deployment. Then start services, load and validate the OpenSearch index, create the initial admin interactively, verify /review over HTTPS, and create the required post-setup baseline backup described in BACKUP.md. Record the backend image ID for drift checks:

    sudo sh -c 'docker compose --env-file /etc/akyldash/production.env -f /opt/akyldash/current/deploy/production/compose.yaml ps --quiet backend | xargs -r docker inspect --format "{{.Image}}" > /opt/akyldash/deployed-image.txt'
    sudo chmod 0600 /opt/akyldash/deployed-image.txt
    

Application deployment remains owner-run. The repository-scoped act_runner 0.2.13 service is active under akyldash-runner and uses rootless Docker on a separate loop-backed filesystem. CI run 75 and smoke run 76 succeeded on main head 0e276ae6. Runner job containers have neither Docker socket nor production secrets. CI has no image publishing or production deployment step. The repository defines sudo helpers for fixed verification, read-only Compose config/status, and guarded rollback, but none is installed on the VPS. They do not start or stop services.

Release image contract (preparation only)

infra/deploy/validate_release.py checks an offline JSON release manifest against an explicitly supplied repository allowlist. Schema version 1 requires exactly schema_version, source_ref, commit, and images; the source ref must be refs/heads/main, the commit must be a 40-character lowercase Git SHA-1, and the images must contain exactly backend and opensearch as repository@sha256:<64 lowercase hex> references. The policy has schema version 1 and one non-empty repository allowlist for each service. Unknown or duplicate JSON keys are rejected.

The validator takes the manifest path and an explicit policy path:

python3 infra/deploy/validate_release.py release.json --policy /etc/akyldash/release-policy.json

The policy shape is {"schema_version":1,"repositories":{"backend":["registry.invalid/akyldash/backend"],"opensearch":["registry.invalid/akyldash/opensearch"]}}. These registry.invalid names are format examples only; this change does not create a policy file or approve a registry.

The repository name in the policy must be approved for the registry. No real registry namespace or root-owned host policy is configured by this change; do not use the synthetic registry.invalid names in tests as production values. The host integration must load policy only from its fixed root-owned path. This validator checks format and allowlist only: a manifest can claim a main ref and commit, but is not proof of source, build provenance, signature, or trusted publication. CI still has no publish credentials, image publication, host helper, or deploy trigger.

Compose merges an image override with the existing service build entries. The regression test renders fake digest references and confirms both entries remain; any future deploy command must use docker compose up --no-build so the host cannot silently build a different image. This does not make digest rollback available: the current rollback helper expects local tags. A separate host-side deploy/rollback design, owner-approved registry permissions and retention, and manual backup/health/rollback end-to-end validation are still required before publishing or enabling CD.

CI

.gitea/workflows/ci.yaml runs the Python unit suites and builds both production images on pull requests and pushes to main. It does not publish an image or deploy production. .gitea/workflows/runner-smoke.yaml exercises the akyldash-ci runner on pull requests, pushes to main, or manual dispatch. Both workflows passed on main head 0e276ae6 in runs 75 and 76 respectively. The repository runner-list endpoint is not available to the current API principal, so its registration details cannot be independently read through Gitea API.