Skip to content

Configuration and modules

Each host has one installation, deploy/installations/<name>/. Its installation.ts (committed) names the Mainline Packages it installs, the modules it enables and every value that differs between hosts; its secrets.toml (git-ignored, mode 0600) holds the credentials. The launcher renders the two into .rendered/ and runs Docker Compose with what it rendered. No environment file is read and the developer shell’s variables are not passed to the containers.

Terminal window
bun run deploy modules # every module, its package and Compose profile
bun run deploy init staging # write secrets.toml: generated values, SET_ placeholders
bun run deploy check staging # config, secrets and each module's own parser
bun run deploy render staging # write .rendered/ and run docker compose config --quiet
bun run deploy compose staging -- config --services

A package is installed when its key is present under packages; a module is enabled when its key is present under that package’s modules (or base.modules). The schema is strict: an unknown key is an error that names it. The launcher derives the Compose profiles, the provider keys Mainframe needs and the overlays (GenericDrone, receivers, derivatives) from the modules alone.

Package Module (Compose profile) What it runs
Base (always) — (core) Mainframe, Postgres, SRS, indexer, derivatives, Caddy
Base weather Weather from Open-Meteo, or from the simulator (source: "simulator")
Base detections, assistant Paid vision analysis; the on-page assistant’s model proxy (base.openrouterApiKey)
Base front Native Android phones (publicUrl)
Drones autel Native Autel controller host and its authenticated broker (nativeDir/native.json)
Drones generic-drone Authenticated JSON telemetry and video from generic drones
Air Picture fusion, radar-net Sensor feeds, fused tracks, identity; external radar devices
Comms voice LiveKit, Redis and Egress
TAK tak (interop) TAK bridge with mutual TLS (certDir)
Simulation world-sim (world) Virtual aircraft, cameras, the standing air world and the operator
Legacy vanagas, vanagas-phones The ids resolve; nothing is rendered. Run them by hand
— monitoring key (monitoring) Grafana, Prometheus, Alertmanager, exporters, Loki, Alloy
— base.storage.bundled (storage), base.media.forensic (forensic) The bundled RustFS; ingress TCP capture

deploy/installations/staging/installation.ts is the worked example. Key reference:

Key Meaning
name, kind, project Short name Terminal shows (SAB, Staging); dev, staging, production or archive; the Compose project, terminal-<kind> by default. Keep project stable: it names the volumes
host domain, publicIp (SRS’s and LiveKit’s browser-reachable address), tlsEmail, siteAddress, dockerDataRoot, terrainDir (the DEM tiles, mounted read-only into fusion and world-sim), backupRetentionDays
urls mainframe (default https://<domain>), mainframePublic, terminal, trustedOrigins (browser origins allowed to carry credentials)
images, resources Image tags and memory/CPU limits by name
base.storage Private object store: endpoint, bucket, region, publicEndpoint, presign, bundled
base.media rtmpUrl (publishing address for providers), rtcPort (UDP and TCP; 8189 by default, staging 8000), preserveHost, forensic
base.sso, base.invites, base.admin OIDC issuer/clientId (used only while Settings → Security → Single sign-on is on at boot); trusted proxies; the first administrator’s email
packages.air-picture.modules.fusion origin [lat, lon] or [lat, lon, ellipsoid height], groundMsl, threads (empty: min(cores − 2, 8)), rawRetentionDays, quarantineRetentionDays, serialDevice
packages.comms.modules.voice publicUrl (default wss://<domain>), stunServers ([] for a LAN box), recording
packages.simulation.modules.world-sim publicUrl, bindAddress, seed, config, airWorld (standing or none, used only with Air Picture), demo (continuous, threatEveryS, reloadAfterS), liveTraffic, operator
monitoring grafanaUrl, grafanaAdminUser, telegramChatId
archive Required for kind: "archive", refused otherwise: package, mapDir, release, ports
env.<service> The escape hatch: variables merged into that one service’s rendered environment, for a module setting the installation has no key for
Secret (secrets.toml) Variable Source
base.postgresPassword, base.mediaSecret, base.systemApiKey, base.admin.password POSTGRES_PASSWORD, MEDIA_SECRET, MAINFRAME_SYSTEM_API_KEY, MAINFRAME_ADMIN_PASSWORD generated
base.authSecret BETTER_AUTH_SECRET generated (an archive keeps the source’s)
base.storage.accessKey, secretKey BLOB_S3_ACCESS_KEY, BLOB_S3_SECRET_KEY supplied (generated for the bundled RustFS)
…modules.<id>.apiKey MAINFRAME_<ID>_API_KEY generated, one per enabled provider module
base.openrouterApiKey, base.sso.clientSecret OPENROUTER_API_KEY, MAINFRAME_SSO_CLIENT_SECRET supplied
base.modules.weather.openMeteoApiKey WEATHER_API_KEY optional: a paid Open-Meteo plan; empty uses the free, non-commercial endpoint
…generic-drone.databasePassword, databaseUrl GENERIC_DRONE_DATABASE_* generated; supplied
…voice.livekitApiSecret LIVEKIT_API_SECRET generated
…world-sim.adminToken, liveTrafficApiKey WORLD_SIM_ADMIN_TOKEN, WORLD_SIM_LIVE_TRAFFIC_API_KEY generated; supplied when liveTraffic is on (sent only to adsb.lol)
monitoring.grafanaAdminPassword, alertmanagerTelegramBotToken, alertmanagerWebhookUrl GRAFANA_ADMIN_PASSWORD, ALERTMANAGER_* generated; supplied

A leaf may be { file = "/path" } to read the value from a file. check refuses a SET_ placeholder left in place. Mainframe reads its own configuration from the rendered installation.json (MAINFRAME_INSTALLATION); provider keys stay stable across restarts, and changing one does not rotate a key already in the database.

The simulator’s operator is on when operator is present under world-sim, and only where Drones is installed. It dispatches missions only to world-sim’s own aircraft; Mainframe refuses any module a command for another provider’s entity.

Voice media takes two host ports beside rtcPort: 7881/tcp (ICE over TCP) and 7882/udp. LiveKit advertises host.publicIp as its only candidate, so a wrong value means one-way or no audio. Without the voice module /api/voice/config answers enabled: false and the Voice panel says so. Microphones need a secure context: a LAN deployment reached over plain http:// by IP has no microphone.

Editing installation.ts or secrets.toml takes effect when the containers are recreated (bun run deploy up <name>). Changing urls.mainframePublic also requires rebuilding the frontend image. Document edits made through Terminal take effect through Mainframe’s document watches.

The first boot of a database seeds Mainframe’s settings documents from code (apps/mainframe/src/config/defaults.ts); they are never seeded again. Change them afterwards in Mainframe Settings (administrators), where every change is audited. The Settings page describes each section.

Initial value Settings section
State horizon 90 days, telemetry 14 days, bulk 48 hours Retention
Recording retention 168 hours, record policy always, no overrides Media

The launch battery minimum (30 %), the coverage grid (150 m cells, 10 minute horizon, over the AO the workspace names), the workspace defaults and the security values (7 day sessions, 10 sign-ins per 60 s, 12 character passwords, no two-factor requirement, single sign-on off, 365 day personal keys) likewise seed from code and are edited in Settings only. The session age, login limit, single sign-on are read at boot (after restart in Settings); the password floor, the two-factor requirement and the key age apply at once.

Module grants declared in MODULE_GRANTS (apps/mainframe/src/module-grants.ts) are desired state: every boot adds what is missing and removes a configured grant that left the table, and never touches a grant an administrator wrote in Mainframe Settings → Roles or Users.

The engine is selected when Vite builds the frontend. The checked-in apps/web/map-build.json selects Mapbox and supplies its public browser token, so Pages and clean checkouts use the same defaults. Override these in the Pages build environment or the ignored apps/web/.env.local file, then rebuild:

Variable Default Purpose
VITE_MAP_ENGINE mapbox maplibre or mapbox; other values fail the build
VITE_MAPBOX_ACCESS_TOKEN map-build.json Public pk.* token; required for Mapbox builds
VITE_MAP_STYLE unset Optional style URL overriding the chosen engine’s defaults

MapLibre keeps the registered PMTiles → Lithuania archive → CARTO resolution. Mapbox starts with dimmed Satellite Streets imagery (65% maximum brightness, slightly reduced saturation). Labels and operational overlays remain at full brightness. Layers → Satellite / Map switches the basemap in Mapbox builds. Map mode follows the application’s light/dark theme. An explicit VITE_MAP_STYLE fixes the basemap and hides that selector.

Both engines use the same markings, selection, route, drone, camera-footprint, coverage, and detection code. The build selects the matching Terra Draw adapter for vertex editing and the matching GL markers for draggable points and circles. Style changes restore operational layers and the current edit draft. Mapbox uses flat classic styles to keep the existing overlay ordering and canvas coverage projection; custom styles must support these same GL layers and label fonts.

The configured pk.* token is public and included in the browser bundle. Set VITE_MAP_ENGINE=maplibre to build the self-hosted MapLibre variant. Engine changes require a new frontend build; backend environment changes alone do not select an engine.

Set recording: true under packages.comms.modules.voice to enable automatic room mixes and original speaker recording. Provide private bucket access and retain the Egress backup volume during upload outages. Historical audio remains readable with recording disabled.

Recording status and indexed coverage differ: token issuance is not proof of audio capture. Monitor mainframe_voice_recordings, mainframe_voice_recording_reconcile_failures_total and mainframe_comms_purge_pending. Voice uses the Comms retention setting and honors archive preservation holds.

Transcription is deferred: its UI is hidden and no transcription backend runs, even if Whisper settings are present. The local adapter code is retained for future use. Recording, playback and audible-activity analysis do not require a speech model.