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.
bun run deploy modules # every module, its package and Compose profilebun run deploy init staging # write secrets.toml: generated values, SET_ placeholdersbun run deploy check staging # config, secrets and each module's own parserbun run deploy render staging # write .rendered/ and run docker compose config --quietbun run deploy compose staging -- config --servicesA 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.
Initial values
Section titled “Initial values”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.
Frontend map engine
Section titled “Frontend map engine”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.
Voice capture and optional transcription
Section titled “Voice capture and optional transcription”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.