Architecture Overview

This document describes the overall architecture, design principles, and system organization of the Docker Compose orchestration framework.

System Design Principles

1. Modular Architecture

• Each service stack is independent and reusable
• Services can be deployed individually or in combination
• Clear separation of concerns between service layers
• Minimal coupling between services

2. Network Isolation

• 5 isolated Docker networks for security and organization
• Services only connect to networks they need
• Internal networks prevent external access
• Single external-facing proxy network

3. Systemd Integration

• Reliable service orchestration with proper dependency management
• Services start in correct order automatically
• Automatic restart on failure
• Boot-time startup support

4. Configuration Management

• Multi-layered environment system
• Separation of secrets and base configuration
• Machine-specific overrides via .local files
• GitOps-friendly (base config committed, secrets ignored)

Architecture Diagram

┌──────────────────────────────────────────────────────────────────┐
│                         Internet / Local Network                  │
└────────────────────┬─────────────────────────────────────────────┘
                     │
                     ↓
         ┌───────────────────────┐
         │   Traefik (Proxy)     │  ← SSL/TLS Termination
         │   Port 80/443         │  ← Let's Encrypt + Cloudflare
         └───────────┬───────────┘
                     │
         ┌───────────┴───────────┐
         │   proxy Network       │  172.20.0.0/24
         │   (External)          │
         └───────────┬───────────┘
                     │
     ┌───────────────┼───────────────┐
     │               │               │
     ↓               ↓               ↓
┌─────────┐   ┌──────────┐   ┌──────────┐
│Homepage │   │Portainer │   │Services  │
│Dashboard│   │Container │   │(WebUI,   │
│         │   │  Mgmt    │   │Plex,etc) │
└─────────┘   └──────────┘   └────┬─────┘
                                   │
                       ┌───────────┼───────────┐
                       │           │           │
                       ↓           ↓           ↓
              ┌────────────┐  ┌────────┐  ┌────────┐
              │  database  │  │ genai  │  │  auth  │
              │  Network   │  │Network │  │Network │
              │172.22.0/24 │  │172.23/ │  │172.24/ │
              │ (Internal) │  │(Intern)│  │(Intern)│
              └─────┬──────┘  └───┬────┘  └────────┘
                    │             │
        ┌───────────┼─────────────┼──────────┐
        ↓           ↓             ↓          ↓
   ┌─────────┐ ┌─────────┐  ┌────────┐ ┌────────┐
   │MongoDB  │ │Postgres │  │Ollama  │ │LibreChat│
   │         │ │pgvector │  │(LLM)   │ │        │
   └─────────┘ └─────────┘  └────────┘ └────────┘
        ↓           ↓             ↓          ↓
   ┌─────────┐ ┌─────────┐  ┌────────┐ ┌────────┐
   │Qdrant   │ │(Data    │  │OpenWebUI│ │SwarmUI │
   │(Vector) │ │Storage) │  │        │ │(Stable │
   │         │ │         │  │        │ │Diffusion│
   └─────────┘ └─────────┘  └────────┘ └────────┘

Service Layers

Layer 1: Core Infrastructure (panel)

Purpose: Essential services for routing, management, and monitoring

Services:

• Traefik: Reverse proxy with automatic SSL/TLS
• Portainer: Docker container management UI
• Homepage: Unified dashboard for all services

Network: proxy (172.20.0.0/24) - External-facing

Dependencies: None (starts first)

Startup Order: 1st

Layer 2: Data Persistence (database)

Purpose: Centralized data storage and databases

Services:

• MongoDB: NoSQL document database
• PostgreSQL + pgvector: SQL with vector embeddings
• Qdrant: Specialized vector database (GPU-accelerated)

Network: database (172.22.0.0/24) - Internal only

Dependencies: None (but typically starts after panel)

Startup Order: 2nd

Layer 3: AI/ML Services (genai)

Purpose: Artificial intelligence and machine learning capabilities

Services:

• Ollama: Local LLM inference engine
• Open WebUI: Web interface for LLMs
• LibreChat: Advanced chat application
• Text Embeddings: HuggingFace TEI service
• SwarmUI: Stable Diffusion image generation
• RisuAI: Character AI and roleplay

Networks:

• genai (172.23.0.0/24) - Internal
• database (for data storage)
• proxy (for web access)

Dependencies: database, panel

Startup Order: 3rd

Layer 4: Media Services

Purpose: Media streaming and management

Services:

• Plex Media Server: Media streaming (GPU transcoding)
• Tautulli: Plex analytics
• StashApp: Personal media manager

Networks:

• proxy (for web access)
• database (optional, for metadata)

Dependencies: panel

Startup Order: 3rd or 4th

Network Architecture

See Network Topology for detailed network configuration.

Network Isolation Strategy:

Network	Subnet	Type	Purpose	Services
proxy	172.20.0.0/24	External	Internet-facing	Traefik, all web services
database	172.22.0.0/24	Internal	Data persistence	MongoDB, PostgreSQL, Qdrant
genai	172.23.0.0/24	Internal	AI/ML isolation	Ollama, embedding services
metrics	172.21.0.0/24	Internal	Monitoring (future)	Prometheus, Grafana
auth	172.24.0.0/24	Internal	Authentication (future)	Authelia, OAuth providers

Benefits:

• ✅ Security through isolation
• ✅ Clear service boundaries
• ✅ Prevents lateral movement
• ✅ Organized traffic flow
• ✅ Easier firewall rules

Data Flow Examples

Web Request Flow

User Browser
    ↓
    HTTPS (443)
    ↓
Traefik (proxy network)
    ↓
    TLS Termination + Routing
    ↓
Open WebUI (genai + proxy networks)
    ↓
    HTTP (internal)
    ↓
Ollama (genai network)
    ↓
    Vector lookup
    ↓
Qdrant (database + genai networks)

Service Startup Flow

systemd starts services
    ↓
1. panel (Traefik, Portainer, Homepage)
    ↓
    Wait for Traefik ready
    ↓
2. database (MongoDB, PostgreSQL, Qdrant)
    ↓
    Wait for databases ready
    ↓
3. genai services (Ollama, OpenWebUI, etc.)
    ↓
    Wait for dependencies ready
    ↓
All services running

Storage Architecture

Data Directory Structure

${DATA_DIR}/  (default: /mnt/data/compose)
├── panel/
│   ├── traefik/          # Traefik configuration and certificates
│   ├── portainer/        # Portainer data
│   └── homepage/         # Homepage configuration
├── database/
│   ├── mongo/            # MongoDB data files
│   ├── postgres/         # PostgreSQL data files
│   └── qdrant/           # Qdrant vector storage
├── genai/
│   ├── ollama/           # Ollama models
│   ├── openwebui/        # Open WebUI data
│   ├── librechat/        # LibreChat data
│   ├── embedding/        # Embedding models
│   └── swarmui/          # Stable Diffusion models
├── plex/
│   ├── config/           # Plex configuration
│   ├── transcode/        # Transcoding temp files
│   └── media/            # Media library (symlink)
└── stash/
    └── data/             # StashApp data

Volume Mounting Strategy

• Named volumes: For database-specific data (performance)
• Bind mounts: For configuration and shared data
• User namespace mapping: Containers use mapped UIDs/GIDs
• Persistent storage: All data survives container recreation

Security Architecture

Multi-Layer Security

1. Network Isolation: Services only on required networks
2. TLS Everywhere: All external access via HTTPS
3. User Namespace Remapping: Containers don't run as root
4. Secret Management: .local files for sensitive data
5. Minimal Exposure: Only Traefik exposes ports externally

Security Zones

┌─────────────────────────────────────────┐
│  External Zone (proxy network)          │
│  - Traefik only                          │
│  - SSL/TLS termination                   │
│  - Exposed ports: 80, 443                │
└──────────────┬──────────────────────────┘
               │
┌──────────────┴──────────────────────────┐
│  Service Zone (proxy + internal)        │
│  - Web applications                      │
│  - Access via Traefik only               │
└──────────────┬──────────────────────────┘
               │
┌──────────────┴──────────────────────────┐
│  Data Zone (internal networks only)      │
│  - Databases                             │
│  - No external access                    │
│  - Access from service zone only         │
└──────────────────────────────────────────┘

Deployment Scenarios

Scenario 1: Homelab (Recommended)

Characteristics:

• Single server
• Behind NAT/firewall
• Cloudflare DNS for certificates
• No public exposure required

Configuration:

• Use Cloudflare DNS challenge
• All services on same host
• Local network access + VPN for remote

Scenario 2: VPS/Cloud

Characteristics:

• Public IP address
• Internet-facing services
• Cloud provider (AWS, GCP, Hetzner, etc.)

Configuration:

• Direct Let's Encrypt HTTP challenge
• Firewall rules (80, 443 only)
• Consider DDoS protection

Scenario 3: Multi-Host (Future)

Characteristics:

• Docker Swarm or Kubernetes
• Distributed services
• Shared storage required

Configuration:

• Overlay networks
• NFS/Ceph for shared volumes
• Load balancing considerations

Technology Stack

Container Runtime

• Docker Engine: Container runtime
• Docker Compose V2: Service orchestration
• NVIDIA Container Toolkit: GPU support

Service Management

• systemd: Service lifecycle management
• composectl: Custom systemd controller
• compose wrapper: Enhanced Docker Compose

Networking

• Docker Bridge Networks: Network isolation
• Traefik: Reverse proxy and load balancer
• Let's Encrypt: Automatic SSL/TLS certificates

Storage

• Bind Mounts: Configuration and shared data
• Named Volumes: Database performance
• User Namespace Remapping: Security

Languages & Tools

• Python 3.11+: Management scripts
• YAML: Service definitions
• TOML: Network configuration
• Bash: Shell scripts

Scalability Considerations

Current Design

• Single-host: All services on one machine
• Vertical scaling: Add more CPU/RAM/GPU
• Resource limits: Docker resource constraints

Future Scaling Options

1. Service Separation: Move databases to dedicated hosts
2. Docker Swarm: Multi-host orchestration
3. Kubernetes: Enterprise-grade orchestration
4. Load Balancing: Multiple instances of services
5. Database Clustering: MongoDB replica sets, PostgreSQL streaming replication

Design Trade-offs

Chosen Approach: Systemd + Compose

✅ Simple to understand and maintain ✅ No external dependencies (Kubernetes, etc.) ✅ Reliable startup and dependency management ✅ Perfect for homelab and small deployments ✅ Full Docker Compose compatibility

❌ Single-host limitation ❌ Manual scaling required ❌ Not suitable for large-scale production

Alternative: Docker Swarm

✅ Multi-host support ✅ Built-in load balancing ❌ More complex setup ❌ Limited ecosystem compared to Kubernetes

Alternative: Kubernetes

✅ Industry standard ✅ Massive ecosystem ✅ Advanced features ❌ Steep learning curve ❌ Overkill for homelab ❌ Resource overhead

Monitoring & Observability

Current State

• Docker container logs via docker logs
• systemd journal logs via journalctl
• Traefik dashboard for routing
• Portainer for container overview

Future Enhancements

• Prometheus metrics collection
• Grafana dashboards
• Loki log aggregation
• Alert manager for notifications

See: Network Topology for metrics network setup

---

Related Pages:

• Network Topology - Detailed network architecture
• Systemd Integration - Service management
• Configuration Management - Environment configuration