Deployment

How the Engine sits on a host, who it talks to, how its configuration resolves, and where the line falls between what it manages and what you own.

Single-host topology

The canonical deployment is one Linux host: the Engine under systemd, PostgreSQL and ChromaDB as containers, an inference server local or LAN-reachable. Everything inbound crosses the reverse proxy — where TLS and identity are enforced, because the Engine itself trusts whatever reaches it.

flowchart TB
    CLIENT["Your orchestrator / team<br/>(trusted network)"]
    PROXY["Reverse proxy<br/>TLS · identity · generous timeouts"]

    subgraph HOST["Single Linux host"]
        ENG["The Engine<br/>systemd: aetherium.service<br/>:5257"]
        subgraph DOCKER["Docker"]
            PG[("PostgreSQL<br/>:5432")]
            CH[("ChromaDB<br/>:8000 · ext4 volume")]
        end
        LM["LM Studio<br/>:1234 (local or LAN)"]
    end

    CLIENT -->|HTTPS| PROXY
    PROXY -->|"http :5257"| ENG
    ENG --> PG
    ENG --> CH
    ENG -->|"/v1 inference"| LM

    classDef engine fill:#B87333,stroke:#2D2D2D,stroke-width:2px,color:#FFFFFF
    class ENG engine

→ §14 — Deployment

Integration peers

Outbound, the Engine is a client to inference, search, and image generation. Inbound, an external orchestrator drives it over HTTP and receives signed webhook callbacks.

graph TB
    EXT["Your external orchestrator"]
    ENG["The Aetherium Engine"]
    LM["LM Studio — inference"]
    SX["SearXNG — web search"]
    CF["ComfyUI — image generation"]

    EXT -->|"POST /api/orchestrator/run"| ENG
    ENG -.->|"signed webhook POST"| EXT
    ENG -->|"OpenAI-compat /v1 + native /api/v0"| LM
    ENG -->|"GET /search?format=json"| SX
    ENG -->|"REST submit-then-poll"| CF

→ §13 — Integrations

Configuration precedence

A value resolves lowest-to-highest; a higher layer wins. appsettings.Local.json is appended last, so it outranks environment variables; SystemSettings is consulted at runtime and needs no restart.

flowchart TB
    A["appsettings.json<br/>committed defaults"]:::base --> B["appsettings.{Environment}.json<br/>per-environment overlay"]
    B --> C["Environment variables"]
    C --> D["appsettings.Local.json<br/>your gitignored overrides"]
    D --> E["SystemSettings table<br/>runtime knobs · no restart"]:::top

    classDef base fill:#D5C3B0,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A
    classDef top fill:#B87333,stroke:#2D2D2D,stroke-width:2px,color:#FFFFFF

→ §09 — Configuration · the full key list in the Config Reference

Self-managing vs. operator-owned

The Engine manages part of its own lifecycle and leaves the rest to you. Monitoring tells you the left side is working; the right side only happens if you set it up.

flowchart LR
    subgraph ENGINE["The Engine manages it — you monitor"]
        direction TB
        M1["Auto-applies migrations at startup"]
        M2["Container cleanup: idle, stop, destroy"]
        M3["Workspace-tier and archive retention"]
        M4["Background health probes, log ingestion"]
    end
    subgraph YOU["You own it — you set up"]
        direction TB
        O1["Backups: PostgreSQL, ChromaDB, workspaces"]
        O2["Audit-table pruning"]
        O3["Auth boundary, secret rotation"]
        O4["Rollback procedure"]
    end

    classDef owned fill:#B87333,stroke:#2D2D2D,stroke-width:2px,color:#FFFFFF
    class O1,O2,O3,O4 owned

→ §15 — Operations