Repository navigation
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).
| 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.
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).
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).
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.
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
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference