Skip to content

Container and Deployment

MAVERICK edited this page Nov 13, 2026 · 2 revisions

Container and Deployment

How ViaFrei API is packaged and run, and why. The how-to (commands, tags, verification) is in the repository: docs/container.md. Implemented in milestone 0.2.0 (issue #3).

The image

Decision Choice Reason
Base distroless/static (non-root variant), pinned by digest no shell, no package manager, nothing to patch but the binary; a digest pin makes the build reproducible and Dependabot-updatable
Build multi-stage, pinned Go builder, CGO_ENABLED=0, -trimpath, stripped, version and commit stamped in a static binary needs no libc in the final stage; the stamped version is what /v1/meta and viafrei-api version report
Platforms linux/amd64 and linux/arm64 the service may run on either; both are built on every pull request
User nonroot (65532) the process needs no privilege
Filesystem read-only at run time the service writes no file; logs go to stdout
Secrets none in the image the database URL is given at run time, from an environment variable or a mounted file (*_FILE); CI scans every layer for secrets
Health viafrei-api healthcheck asks the service's own /healthz a distroless image has no curl, so the binary is its own probe
Bad configuration exit status 78 at boot, every violation listed a container that cannot be configured must not start and wait for traffic

Resource limits for one instance are design targets until the benchmark measures them: 256 MiB of memory, one CPU, 128 processes.

Tags and digests

Images are published for confirmed releases only: an annotated vX.Y.Z tag that equals version.txt, on a commit from main (or a reviewed hotfix branch) whose required CI checks completed with success. A tag is never re-pushed. A push to main and a release candidate publish no image; CI still builds, scans and smoke-tests every commit's image without pushing it.

Tag Set by Moves
X.Y.Z a confirmed release never
X.Y a confirmed release to the newest patch of that minor
latest a confirmed release that is the highest version to the newest release

Deployments reference digests, never tags. A rollback is a redeploy of an earlier digest (Release Process).

Supply chain

Every published image is:

  • signed with cosign, keyless, with the GitHub OIDC identity of the one publishing workflow, release.yml
  • attested with SLSA build provenance and an SPDX SBOM
  • scanned by Trivy (HIGH and CRITICAL fail) and linted by Hadolint before it is pushed

The verification commands are on every release page and in docs/container.md. Requirements: Spec: Secure SDLC and Supply Chain (SSC-003, SSC-005).

Local stack

compose.yaml in the repository runs two services for development and the CI smoke test:

  • db: PostGIS, built with the read-contract stub, the read-only role and a synthetic fixture set (Test Data Management). It sits on an internal network, publishes no port and keeps its data in a named volume.
  • api: the runtime image, connected through the read-only role, with every capability dropped, a read-only filesystem and no-new-privileges, published on the loopback address only.

make up, make down, make reset and make compose-test (healthz, readyz, meta and a Schemathesis run, then teardown) drive it. No real data and no secret is in the repository: .env.example holds placeholders, and a conformance test refuses a password written into compose.yaml.

Deployment

There is no public deployment yet (Project Status). When there is one, it pulls a signed image by digest, verifies the signature and the provenance before it starts, runs read-only with the limits above, and reaches the platform's database through the read-only role only. Where it runs first is an open decision on Project Status.

See also: Release Process · Architecture: Go · Spec: CI/CD and Release · Spec: Operations

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally