victus-infra is a repository-owned infrastructure runtime for the Victus
ecosystem.
The system is shaped around a single runtime source of truth:
compose/ -> Docker Compose definitions and service configuration
ansible/ -> host orchestration and deployment of repository-owned files
ops/ -> support tooling for validation, runtime tasks, and migrations
Docker Compose defines the service topology. Ansible prepares the VPS,
places runtime files, stages secret-dependent configuration, and starts the
same Compose-defined stacks on the server.
The architecture separates infrastructure by domain so each stack can be
reasoned about and deployed independently.
Detailed architecture is split into focused modules:
architecture/101-NETWORKING.md Tailscale, Docker networks, CoreDNS
architecture/102-COMPUTE-RUNTIMES.md Docker Compose, Ansible, stack runtime
architecture/103-DATA-STORAGE.md SeaweedFS, Postgres, Redis, volumes
architecture/104-OBSERVABILITY.md Prometheus, Loki, Langfuse
The core stack owns shared infrastructure required by Victus consumers.
compose/projects/core/
Primary responsibilities:
Components:
nginx-private private HTTP edge
nginx-public public HTTP/TLS edge
seaweedfs S3-compatible object storage
pipeline-postgres durable pipeline database
redis durable event stream
etcd CoreDNS backend state
coredns private DNS for victus.io
Inputs:
compose/projects/core/compose/configs/Outputs:
The wiki stack owns public Wiki.js documentation.
compose/projects/wiki/
Components:
wiki Wiki.js application
wiki-database Wiki.js Postgres database
The wiki service joins infra_shared_backend so nginx-public can proxy
the public docs hostname to wiki:3000. The database remains on the internal
wiki_backend network.
The observability stack owns runtime visibility.
compose/projects/observability/
Components:
prometheus metrics collection
loki log storage and querying
Inputs:
compose/projects/observability/compose/configs/Outputs:
The llm stack owns LLM gateway key management and LLM observability.
compose/projects/llm/
Components:
llm-postgres durable LiteLLM and Langfuse databases
litellm OpenAI-compatible LLM gateway and virtual key manager
langfuse LLM tracing, cost, and audit surface
Inputs:
compose/projects/llm/compose/configs/litellm/Outputs:
40003001 and container port 3000The deployment layer owns host preparation and stack rollout.
ansible/playbooks/
ansible/roles/deploy/
Responsibilities:
Boundaries:
Operational tooling supports local validation, runtime checks, and shared
database lifecycle tasks.
ops/
tests/
Responsibilities:
core shared runtime services and edge routing
observability monitoring and logging services
llm LLM gateway, key management, tracing, and cost audit
wiki public documentation runtime
ansible host orchestration and deployment
ops validation and runtime support tooling
docs repository documentation hubs and nodes
Each boundary should remain explicit in paths and documentation.
The architecture depends on external systems for execution and automation:
VPS host production runtime target
GitHub Actions deployment automation
Infisical secret source through OIDC
Docker Engine container runtime
consumer repos external systems using shared runtime services
This repository owns infrastructure shape and shared runtime contracts.
Consumer repositories own:
developer
-> Compose project files
-> local overrides and env files
-> local Docker runtime
-> core and/or observability services
Local execution validates the same service topology used for server mode,
with local overrides and local environment values.
GitHub Actions
-> Infisical OIDC secrets
-> Ansible playbooks
-> VPS filesystem and runtime config
-> Docker Compose up
-> deployed stack services
Server execution keeps Compose as the runtime definition while Ansible owns
the host-level rollout sequence.
consumer repository
-> shared infrastructure endpoint
-> Postgres for durable registry state
-> SeaweedFS S3 for artifacts
-> Redis Streams for durable events
-> private DNS for service discovery
Consumer systems interact with infrastructure through stable endpoints and
shared contracts. Detailed contract guarantees live in
300-CONTRACTS.md.
The runtime supports artifact and state movement for downstream Victus
systems.
source artifact
-> SeaweedFS S3 object storage
-> Postgres registry state
-> Redis Streams event notification
-> external consumers and workers
Storage, registry, and event stream responsibilities are separated:
The architecture treats Postgres as the durable state anchor and Redis Streams
as the operational event transport.
Runtime topology is defined in checked-in Compose files, which keeps local
and server execution aligned.
Environment-specific behavior is expressed through env files, overrides, and
deployment context rather than separate runtime definitions.
Stacks are separated by domain, allowing targeted validation, deployment, and
inspection.
Persistent data is isolated from runtime configuration through explicit host
filesystem areas and service volumes.
Monitoring and logging are modeled as a dedicated stack instead of being
embedded into application or core service ownership.
Consumer repositories depend on stable infrastructure endpoints and contracts,
not on internal deployment mechanics.
Docker Compose runtime topology and stack execution
Docker Engine container runtime on local and server environments
Ansible host orchestration and deployment
GitHub Actions CI/CD automation
Infisical secret retrieval through OIDC
SeaweedFS S3-compatible object storage
Postgres durable registry state
Redis Streams durable event stream
CoreDNS/etcd private DNS service and backing store
Prometheus metrics collection
Loki log aggregation