Binaries and source builds

Binaries and source builds

The simplest stable server installation is Docker Compose. A viat executable is the management CLI, not a combined server installer. The server executable is viat-api. This page covers identifying those binaries and building a pinned source checkout when you deliberately maintain a developer-managed installation.

Before choosing this path

You need permission to install/run software on the host, a PostgreSQL database you control, protected secret storage, and a valid activation code for the verification key in your chosen server build. Building from source does not bypass activation and does not make customer-side signing-key generation an activation procedure.

For a source build, also provide:

• The release’s Rust toolchain (rust-toolchain.toml pins 1.98), Cargo, a C linker and platform development libraries required by its dependencies.
• Node/npm if you want to build the browser console; use the repository-root lockfile/workspaces, not independent installs inside web/.
• uv for Python scripts, bun for TypeScript, and Bash/jq for the shell capabilities you intend to use. Compiling the server does not install those interpreters.
• Network access for the build dependencies and, when needed, runtime package installations.

This is not a promise of downloadable native server packages or signed Windows/Linux desktop releases. For Apple client artifact installation and its bundled CLI, see Clients. No public artifact download URL is established by this handbook.

Identify what you have

For an already installed CLI:

command -v viat
viat --version
viat version

viat --version should report viat 1.1.0 for this baseline. viat version always reports the CLI and adds the server release only when a configured session can read /version. “Version unavailable” is not proof that the binary is wrong; it can indicate missing login, network failure, or an older server.

The official container carries /usr/local/bin/viat-api and /usr/local/bin/viat. Do not copy a Linux binary out of the image and assume it will execute on macOS or Windows. Its architecture and shared-library requirements still apply.

Build the stable source deliberately

Use a product checkout obtained through your authorized source distribution. In its root, confirm the server/CLI release commit before compiling:

git checkout --detach fd340879
git rev-parse HEAD

fd340879 is the server/CLI 1.1.0 release baseline. The later documentation-contract baseline 03751a67 also contains Apple release-entry tooling; it is not a reason to treat every later branch as a new stable server release. Do not check out or ship unreleased Widget/APNs branches under the stable label.

Containerized source build

With Docker available, an explicit target avoids accidentally building the final build-capable stage:

docker build --target runtime -t viat-local:1.1.0 .

Expected outcome: a local image containing server, CLI, console, and reference book. This command builds locally; it does not push an image or install a running service. It requires substantial time, disk, and dependency downloads. The Dockerfile uses the committed SQLx cache for compilation. To deploy this locally built image, adapt the viat.image in Docker Compose to viat-local:1.1.0 and retain all runtime configuration and storage requirements.

For a Rust-compiling server node, select the other target explicitly:

docker build --target runtime-build -t viat-local:1.1.0-build .

The build variant adds the compiler and matching SDK. It does not remove the need for durable artifact storage, database backups, activation, or runtime limits.

Native developer build

From the pinned product root:

SQLX_OFFLINE=true cargo build --release --locked -p viat-api -p viat-cli
npm ci
npm run build:web

Expected executables are target/release/viat-api and target/release/viat; browser files are web/dist. SQLX_OFFLINE=true uses the checked-in .sqlx/ descriptions for this unchanged release. It is not a substitute for regenerating the cache when maintaining modified SQL. Ordinary online SQLx compilation instead requires a live, migration-compatible PostgreSQL database at compile time. A cache mismatch is a reason to restore a consistent source/cache pair—not to edit query metadata blindly.

The npm steps are unnecessary for a headless management API/CLI setup, but without built files and VIAT_WEB_DIR, a native server does not magically contain the console. This sequence does not build native apps, run tests, create a system service, or install tools on your PATH.

Configure a source-built server

Prepare an empty PostgreSQL database with a dedicated login. For the bootstrap, the login needs privileges to apply the platform’s migrations. Do not point an experimental build at an existing production database.

In a Bash session at the product root, set values privately:

read -r -s -p 'PostgreSQL URL: ' DATABASE_URL; printf '\n'
export DATABASE_URL
read -r -s -p 'Master key (64 hex characters): ' VIAT_MASTER_KEY; printf '\n'
export VIAT_MASTER_KEY
read -r -s -p 'JWT secret: ' VIAT_JWT_SECRET; printf '\n'
export VIAT_JWT_SECRET
read -r -p 'Initial owner email: ' VIAT_DEFAULT_ADMIN_EMAIL
export VIAT_DEFAULT_ADMIN_EMAIL
read -r -s -p 'Initial owner password: ' VIAT_DEFAULT_ADMIN_PASSWORD; printf '\n'
export VIAT_DEFAULT_ADMIN_PASSWORD
export VIAT_BIND=127.0.0.1:8080
export VIAT_ALLOW_REGISTRATION=false
export VIAT_WEB_DIR="$PWD/web/dist"
./target/release/viat-api

Use a PostgreSQL URL such as postgres://USER:PASSWORD@HOST:5432/DATABASE with actual values and percent-encoding where necessary. Generate the master key with openssl rand -hex 32 once, save it securely, and re-use it. Generate a separate strong JWT secret. The native default JWT value dev-secret-change-me is not safe for any real deployment. These prompts avoid putting literal passwords in shell history; environment variables and local process access remain a host-security concern.

The server applies migrations at startup. If your platform database or master key is missing, startup fails. The initial Owner is seeded only once; environment changes do not overwrite an existing password. For a persistent service, move configuration into protected service-manager credentials/configuration rather than relying on an interactive shell.

If you skipped the console build, omit VIAT_WEB_DIR and use CLI/API login. If you want a console, ensure web/dist exists before starting. Set VIAT_LICENSE_CODE privately for startup activation, or sign in and follow Activation.

Verify and diagnose

From a second terminal:

curl --fail --silent --show-error http://127.0.0.1:8080/healthz
curl --fail --silent --show-error http://127.0.0.1:8080/readyz
./target/release/viat --version

Expect HTTP 200 from liveness ({"status":"ok"}), readiness 200 for a usable database, and CLI viat 1.1.0. A healthy process may still be unactivated. Follow Your first endpoint for a genuine publish/call verification.

Failure	Remedy
DATABASE_URL must be set	Export a URL for the platform PostgreSQL database, not a resource SQLite file
VIAT_MASTER_KEY must be set / invalid hex	Supply the saved 64-hex-character master key
Build cannot find SQLx query data	Use the matching release cache; modified SQL needs a live compile database and cache regeneration
/ui/ unavailable	Build web/dist and set VIAT_WEB_DIR, or use headless CLI/API intentionally
Python/TypeScript runtime cannot start	Install the chosen interpreter on the server’s PATH; a successful Rust build did not install it
Rust script will not compile	Verify matching compiler/SDK/build capability, not merely the existence of the CLI

Stop and clean up

Use Ctrl-C for an interactive server and wait for shutdown. Keep the database and saved master key if you want to resume. Removing target/ removes local build products, not the platform database or server-created application files. Drop only a deliberately disposable database through your normal database-administration process. Do not use an untested older binary against a migrated database as a rollback plan.

Verification basis

Server release fd340879; contract source 03751a67: Cargo.toml, rust-toolchain.toml, Dockerfile, root package.json, crates/viat-api/src/{config,main}.rs, and crates/viat-cli/src/commands/auth.rs.