Alpha. Vary is under active development and not ready for production use. Syntax, APIs, performance, and behaviour may change between releases.

Architecture

Via runs Vary apps on one Ubuntu host. It owns the path from source intake through tests, artifact signing, runtime launch, configuration delivery, add-on bindings, domain policy, and public routing.

Operators manage the host with via. App owners deploy and inspect apps with vary.

Service roles

The main Via services are installed as systemd units. Each service has a narrow job and reports health through via status and via doctor.

Service	Role
Control plane	Owns apps, users, sessions, releases, operations, audit, source intake, domains, routes, and add-on state.
Builder	Checks out source, typechecks, tests, packages, and signs Vary app releases.
Runner	Verifies signed artifacts, starts runtime containers, promotes healthy deploys, and records runtime state.
Config server	Serves authorized config, secret values, and add-on descriptors to running apps.
Proxy	Publishes approved public routes to the current healthy runtime target.
Test runner	Runs queued app test jobs and records results.

Control-plane state

The control plane is the source of truth. It records app identity, release history, build state, runtime state, config profile versions, bindings, domains, routes, operations, audit, and backup metadata.

Worker services report mutations through internal control-plane APIs instead of each daemon independently writing platform state. That keeps build, deploy, route, and runtime transitions ordered and auditable.

For operator debugging, via doctor reports writer role, SQLite journal mode, busy timeout, and internal API compatibility.

Host components

Via uses host components, but operators should change Via state through via and vary commands rather than hand-editing generated files or container state.

Component	Used for	Managed by
systemd	Starts and supervises Via services.	Host OS and `via install`.
Docker	Runs Vary build jobs and app runtime containers.	Docker daemon, with Via creating and supervising containers.
Git HTTP backend	Accepts app source pushes over the Via-hosted Git endpoint.	Ubuntu `git` package, invoked by the control plane.
SQLite	Stores platform state such as apps, releases, users, operations, audit, routes, domains, bindings, and add-ons.	Via state directory.
Vary toolchain	Typechecks, tests, compiles, and packages Vary apps during builds.	Via toolchain store and builder environment.
Public proxy	Terminates HTTPS and routes approved public traffic.	Host package plus Via-managed service/config/state.

Storage layout

Via keeps durable server state under the Via state directory and host configuration under the Via config directory. The exact paths can be configured, but the default layout is what most installations use.

Area	Default path	Contains
Config	`/etc/via/`	Server config, routing policy, generated proxy config.
State	`/var/lib/via/`	Control-plane database, identity keys, source repositories, artifacts, build state, runtime state, add-ons, toolchains, and proxy state.
Logs	`/var/log/via/`	Service log files that mirror the systemd journal.

Backups are based on this split. A normal backup captures config, database state, identity material needed for verification, repositories, artifacts, and add-on data. Secret recovery material is opt-in because it can decrypt protected app values.

Deploy lifecycle

A deploy starts on the app owner's workstation. It finishes after Via has tested, built, signed, verified, launched, configured, and routed the app. The previous healthy runtime keeps serving if a new build or deploy fails.

Stage	Owner	What happens
Source push	App owner	`vary app deploy` pushes committed source to the server-hosted Git endpoint.
Intake	Control plane	The server authenticates the push, validates the target app and ref, and records a queued deploy.
Build	Builder	The builder checks out source, typechecks, tests, compiles, packages, and signs the artifact.
Artifact	Control plane	Signed artifact metadata is recorded with the deploy and build result.
Launch	Runner	The runner verifies the signature and starts or supersedes the runtime container.
Bind	Config server	Runtime config, secrets, and add-on descriptors are authorized for the running release.
Route	Proxy	Approved domains and routes point to the healthy runtime target.

Via separates deployment from public routing. A successful deploy proves that the server built and launched an app. A route proves that the hostname is allowed, verified, approved when required, covered by a certificate, and free of conflicts.

Runtime boundary

App runtimes run in Docker containers launched by Via. Runtime access is intentionally narrow:

Boundary	Rule
Artifact	Runner starts only a verified signed artifact.
Identity	Runtime gets a short-lived workload token.
Config	Runtime asks the config server for authorized keys.
Add-ons	Runtime fetches descriptors by binding name.
Traffic	Public routes point only at the current healthy runtime.
Inspection	App owners use `vary app status`, `inspect`, and `logs`; no host shell is required.

Config and add-ons

The config server is the boundary between a running app and protected runtime material. Plaintext secret values are not written into source, build logs, image layers, deploy commands, app-owner status output, or route metadata.

Add-ons are resources attached to apps through named bindings. A deploy snapshots the binding set, and the running app fetches descriptors by binding name.

Add-on concern	Via behavior
Storage	Resource data lives under Via-managed state.
Binding	Operators bind a resource to an app under a stable name such as `DATABASE`.
Runtime access	Apps request the descriptor by binding name through the config server.
Credential rotation	Via can rotate descriptor credentials while keeping the app-facing binding name stable.
Snapshot and restore	Operators use Via add-on commands so state, audit, and runtime safety stay consistent.

Continue to Deploy lifecycle for deploy phases, Add-ons for the managed resource model, Domains and routes for public traffic policy, or Services and logs for service-level operation.

Config redeploys Domains and routes