Ouranos Lab - Red Panda Approved Infrastructure

Project Overview

Ouranos is a comprehensive infrastructure-as-code project that provisions and manages a complete development sandbox environment. All infrastructure and configuration is tracked in Git for reproducible deployments.

DNS Domain: Incus resolves containers via the .incus suffix (e.g., oberon.incus). IPv4 addresses are dynamically assigned — always use DNS names, never hardcode IPs.

Terraform

Provisions the Uranian host containers with:

10 specialised Incus containers (LXC)
DNS-resolved networking (.incus domain)
Security policies and nested Docker support
Port proxy devices and resource dependencies
Incus S3 buckets for object storage (Casdoor, LobeChat)

Idempotent, elegant, observable

Ansible

Deploys and configures all services:

Docker engine on nested-capable hosts
Databases: PostgreSQL (Portia), Neo4j (Ariel)
Observability: Prometheus, Loki, Grafana (Prospero)
Application runtimes and LLM proxies
HAProxy TLS termination and Casdoor SSO (Titania)

Idempotent, auditable, integrated

Uranian Host Architecture

Hosts Summary

Name	Role	Key Services
ariel	graph_database	Neo4j 5.26.0
caliban	agent_automation	Agent S MCP Server, Kernos, MATE Desktop, GPU
miranda	mcp_docker_host	MCPO, Grafana MCP, Gitea MCP, Neo4j MCP, Argos MCP
oberon	container_orchestration	MCP Switchboard, RabbitMQ, Open WebUI, SearXNG, Home Assistant, smtp4dev
portia	database	PostgreSQL 16
prospero	observability	Prometheus, Loki, Grafana, PgAdmin, AlertManager
puck	application_runtime	JupyterLab, Gitea Runner, Django apps (6×)
rosalind	collaboration	Gitea, LobeChat, Nextcloud, AnythingLLM
sycorax	language_models	Arke LLM Proxy
titania	proxy_sso	HAProxy, Casdoor SSO, certbot

oberon — Container Orchestration

King of the Fairies orchestrating containers and managing MCP infrastructure.

Docker engine
MCP Switchboard (port 22785) — Django app routing MCP tool calls
RabbitMQ message queue
Open WebUI LLM interface (port 22088, PostgreSQL backend on Portia)
SearXNG privacy search (port 22073, behind OAuth2-Proxy)
Home Assistant (port 8123)
smtp4dev SMTP test server (port 22025)

portia — Relational Database

Intelligent and resourceful — the reliability of relational databases.

PostgreSQL 16 (port 5432)
Databases: arke, anythingllm, gitea, hass, lobechat, mcp_switchboard, nextcloud, openwebui, spelunker

ariel — Graph Database

Air spirit — ethereal, interconnected nature mirroring graph relationships.

Neo4j 5.26.0 (Docker)
HTTP API: port 25554
Bolt: port 7687

puck — Application Runtime

Shape-shifting trickster embodying Python's versatility.

Docker engine
JupyterLab (port 22071 via OAuth2-Proxy)
Gitea Runner CI/CD agent
Django apps: Angelia (22281), Athena (22481), Kairos (22581), Icarlos (22681), Spelunker (22881), Peitho (22981)

prospero — Observability Stack

Master magician observing all events.

PPLG stack via Docker Compose: Prometheus, Loki, Grafana, PgAdmin
Internal HAProxy with OAuth2-Proxy for all dashboards
AlertManager with Pushover notifications
Prometheus node-exporter metrics from all hosts
Loki log aggregation via Alloy (all hosts)
Grafana with Casdoor SSO integration

miranda — MCP Docker Host

Curious bridge between worlds — hosting MCP server containers.

Docker engine (API on port 2375 for MCP Switchboard)
MCPO OpenAI-compatible MCP proxy
Grafana MCP Server — Grafana API integration (port 25533)
Gitea MCP Server (port 25535)
Neo4j MCP Server
Argos MCP Server — web search via SearXNG (port 25534)

sycorax — Language Models

Original magical power wielding language magic.

Arke LLM API Proxy (port 25540)
Multi-provider support (OpenAI, Anthropic, etc.)
Session management with Memcached
Database backend on Portia

caliban — Agent Automation

Autonomous computer agent learning through environmental interaction.

Docker engine
Agent S MCP Server (MATE desktop, AT-SPI automation)
Kernos MCP Shell Server (port 22021)
GPU passthrough for vision tasks
RDP access (port 25521)

rosalind — Collaboration Services

Witty and resourceful moon for PHP, Go, and Node.js runtimes.

Gitea self-hosted Git (port 22082, SSH on 22022)
LobeChat AI chat interface (port 22081)
Nextcloud file sharing and collaboration (port 22083)
AnythingLLM document AI workspace (port 22084)
Nextcloud data on dedicated Incus storage volume

titania — Proxy & SSO Services

Queen of the Fairies managing access control and authentication.

HAProxy 3.x with TLS termination (port 443)
Let's Encrypt wildcard certificate via certbot DNS-01 (Namecheap)
HTTP to HTTPS redirect (port 80)
Gitea SSH proxy (port 22022)
Casdoor SSO (port 22081, local PostgreSQL)
Prometheus metrics at :8404/metrics

External Access via HAProxy

Titania provides TLS termination and reverse proxy for all services. Base domain: ouranos.helu.ca — HTTPS port 443, HTTP port 80 (redirects to HTTPS). Certificate: Let's Encrypt wildcard via certbot DNS-01 (Namecheap).

Route Table

Subdomain	Backend	Service
`ouranos.helu.ca` root	`puck.incus:22281`	Angelia (Django)
`alertmanager.ouranos.helu.ca`	`prospero.incus:443` SSL	AlertManager
`angelia.ouranos.helu.ca`	`puck.incus:22281`	Angelia (Django)
`anythingllm.ouranos.helu.ca`	`rosalind.incus:22084`	AnythingLLM
`arke.ouranos.helu.ca`	`sycorax.incus:25540`	Arke LLM Proxy
`athena.ouranos.helu.ca`	`puck.incus:22481`	Athena (Django)
`gitea.ouranos.helu.ca`	`rosalind.incus:22082`	Gitea
`grafana.ouranos.helu.ca`	`prospero.incus:443` SSL	Grafana
`hass.ouranos.helu.ca`	`oberon.incus:8123`	Home Assistant
`id.ouranos.helu.ca`	`titania.incus:22081`	Casdoor SSO
`icarlos.ouranos.helu.ca`	`puck.incus:22681`	Icarlos (Django)
`jupyterlab.ouranos.helu.ca`	`puck.incus:22071`	JupyterLab OAuth2-Proxy
`kairos.ouranos.helu.ca`	`puck.incus:22581`	Kairos (Django)
`lobechat.ouranos.helu.ca`	`rosalind.incus:22081`	LobeChat
`loki.ouranos.helu.ca`	`prospero.incus:443` SSL	Loki
`mcp-switchboard.ouranos.helu.ca`	`oberon.incus:22785`	MCP Switchboard
`nextcloud.ouranos.helu.ca`	`rosalind.incus:22083`	Nextcloud
`openwebui.ouranos.helu.ca`	`oberon.incus:22088`	Open WebUI
`peitho.ouranos.helu.ca`	`puck.incus:22981`	Peitho (Django)
`pgadmin.ouranos.helu.ca`	`prospero.incus:443` SSL	PgAdmin 4
`prometheus.ouranos.helu.ca`	`prospero.incus:443` SSL	Prometheus
`searxng.ouranos.helu.ca`	`oberon.incus:22073`	SearXNG OAuth2-Proxy
`smtp4dev.ouranos.helu.ca`	`oberon.incus:22085`	smtp4dev
`spelunker.ouranos.helu.ca`	`puck.incus:22881`	Spelunker (Django)

Infrastructure Management

Quick Start

# Provision containers
cd terraform
terraform init
terraform plan
terraform apply

# Start all containers
cd ../ansible
source ~/env/ouranos/bin/activate
ansible-playbook sandbox_up.yml

# Deploy all services
ansible-playbook site.yml

# Stop all containers
ansible-playbook sandbox_down.yml

Vault Management

# Edit secrets
ansible-vault edit \
  inventory/group_vars/all/vault.yml

# View secrets
ansible-vault view \
  inventory/group_vars/all/vault.yml

# Encrypt a new file
ansible-vault encrypt new_secrets.yml

Terraform Workflow

Define — Containers, networks, and resources in *.tf files
Plan — Review changes with terraform plan
Apply — Provision with terraform apply
Verify — Check outputs and container status

Ansible Workflow

Bootstrap — Update packages, install essentials (apt_update.yml)
Agents — Deploy Alloy and Node Exporter on all hosts
Services — Configure databases, Docker, applications, observability
Verify — Check service health and connectivity

S3 Storage Provisioning

Terraform provisions Incus S3 buckets for services requiring object storage:

Service	Host	Purpose
Casdoor	Titania	User avatars and SSO resource storage
LobeChat	Rosalind	File uploads and attachments

S3 credentials are stored as sensitive Terraform outputs and in Ansible Vault with the vault_*_s3_* prefix.

Ansible Automation

Playbook	Host(s)	Purpose
`apt_update.yml`	All	Update packages and install essentials
`alloy/deploy.yml`	All	Grafana Alloy log/metrics collection
`prometheus/node_deploy.yml`	All	Node Exporter metrics
`docker/deploy.yml`	Oberon, Ariel, Miranda, Puck, Rosalind, Sycorax, Caliban, Titania	Docker engine
`smtp4dev/deploy.yml`	Oberon	SMTP test server
`pplg/deploy.yml`	Prospero	Full observability stack + internal HAProxy + OAuth2-Proxy
`postgresql/deploy.yml`	Portia	PostgreSQL with all databases
`postgresql_ssl/deploy.yml`	Titania	Dedicated PostgreSQL for Casdoor
`neo4j/deploy.yml`	Ariel	Neo4j graph database
`searxng/deploy.yml`	Oberon	SearXNG privacy search
`haproxy/deploy.yml`	Titania	HAProxy TLS termination and routing
`casdoor/deploy.yml`	Titania	Casdoor SSO
`mcpo/deploy.yml`	Miranda	MCPO MCP proxy
`openwebui/deploy.yml`	Oberon	Open WebUI LLM interface
`hass/deploy.yml`	Oberon	Home Assistant
`gitea/deploy.yml`	Rosalind	Gitea self-hosted Git
`nextcloud/deploy.yml`	Rosalind	Nextcloud collaboration

Playbook	Host	Service
`anythingllm/deploy.yml`	Rosalind	AnythingLLM document AI
`arke/deploy.yml`	Sycorax	Arke LLM proxy
`argos/deploy.yml`	Miranda	Argos MCP web search server
`caliban/deploy.yml`	Caliban	Agent S MCP Server
`certbot/deploy.yml`	Titania	Let's Encrypt certificate renewal
`gitea_mcp/deploy.yml`	Miranda	Gitea MCP Server
`gitea_runner/deploy.yml`	Puck	Gitea CI/CD runner
`grafana_mcp/deploy.yml`	Miranda	Grafana MCP Server
`jupyterlab/deploy.yml`	Puck	JupyterLab + OAuth2-Proxy
`kernos/deploy.yml`	Caliban	Kernos MCP shell server
`lobechat/deploy.yml`	Rosalind	LobeChat AI chat
`neo4j_mcp/deploy.yml`	Miranda	Neo4j MCP Server
`rabbitmq/deploy.yml`	Oberon	RabbitMQ message queue

`sandbox_up.yml`

Start all Uranian host containers

`site.yml`

Full deployment orchestration

`apt_update.yml`

Update packages on all hosts

`sandbox_down.yml`

Gracefully stop all containers

Data Flow Architecture

Observability Pipeline

flowchart LR subgraph hosts["All Hosts"] alloy["Alloy\n(syslog + journal)"] node_exp["Node Exporter\n(metrics)"] end subgraph prospero["Prospero"] loki["Loki\n(logs)"] prom["Prometheus\n(metrics)"] grafana["Grafana\n(dashboards)"] alert["AlertManager"] end pushover["Pushover\n(notifications)"] alloy -->|"HTTP push"| loki node_exp -->|"scrape 15s"| prom loki --> grafana prom --> grafana grafana --> alert alert -->|"webhook"| pushover

Service Integration Points

Consumer	Provider	Connection
All LLM apps	Arke (Sycorax)	`http://sycorax.incus:25540`
Open WebUI, Arke, Gitea, Nextcloud, LobeChat	PostgreSQL (Portia)	`portia.incus:5432`
Neo4j MCP	Neo4j (Ariel)	`ariel.incus:7687` (Bolt)
MCP Switchboard	Docker API (Miranda)	`tcp://miranda.incus:2375`
MCP Switchboard, Kairos, Spelunker	RabbitMQ (Oberon)	`oberon.incus:5672`
All apps (SMTP)	smtp4dev (Oberon)	`oberon.incus:22025`
All hosts (logs)	Loki (Prospero)	`http://prospero.incus:3100`
All hosts (metrics)	Prometheus (Prospero)	`http://prospero.incus:9090`

Important Notes

Alloy Host Variables Required

Every host with alloy in its services list must define alloy_log_level in inventory/host_vars/<host>.incus.yml. The playbook will fail with an undefined variable error if this is missing.

Alloy Syslog Listeners Required for Docker Services

Any Docker Compose service using the syslog logging driver must have a corresponding loki.source.syslog listener in the host's Alloy config template (ansible/alloy/<hostname>/config.alloy.j2). Missing listeners cause Docker containers to fail on start because the syslog driver cannot connect to its configured port.

Local Terraform State

This project uses local Terraform state (no remote backend). Do not run terraform apply from multiple machines simultaneously.

Nested Docker

Docker runs inside Incus containers (nested), requiring security.nesting = true and lxc.apparmor.profile=unconfined AppArmor override on all Docker-enabled hosts.

Deployment Order

Prospero (observability) must be fully deployed before other hosts, as Alloy on every host pushes logs and metrics to prospero.incus. Run pplg/deploy.yml before site.yml on a fresh environment.