docker-compose.yml

# =============================================================================
# usulnet — Docker Management Platform
# =============================================================================
#
# Production-ready Docker Compose configuration.
#
# Quick start:
#   1. cp .env.example .env
#   2. Edit .env (change ALL passwords and secrets)
#   3. docker compose up -d
#   4. Open https://localhost:7443
#   5. Login with: admin / usulnet
#
# With agent (multi-node):
#   docker compose --profile agent up -d
#
# Requirements:
#   - Docker Engine 24+ with Compose v2
#   - 2 GB RAM minimum (4 GB recommended)
#   - Ports 7443 (HTTPS) and 4222 (NATS, agent communication) available
#
# Image registries:
#   - Docker Hub:  usulnet/usulnet          (default)
#   - GHCR:        ghcr.io/usulnet/usulnet  (alternative)
#
# Network architecture:
#   - usulnet-backend: Internal network for PostgreSQL, Redis, NATS
#   - usulnet-frontend: Network for the application and web-facing services
#
# Exposed ports:
#   - 7443  HTTPS (application entry point)
#   - 4222  NATS  (agent communication for multi-node deployments)
#
# Documentation: https://docs.usulnet.com
# Source:        https://github.com/fr4nsys/usulnet
# License:       AGPL-3.0 (Community Edition)
#
# =============================================================================

services:
  # ---------------------------------------------------------------------------
  # usulnet — Application Server
  # ---------------------------------------------------------------------------
  usulnet:
    image: usulnet/usulnet:${USULNET_VERSION:-latest}
    container_name: usulnet
    restart: unless-stopped
    ports:
      # Port 8080 (HTTP) is kept internal for health checks and HTTP→HTTPS redirect.
      # Uncomment the line below only if you need direct HTTP access.
      # - "${USULNET_HTTP_PORT:-8080}:8080"  # HTTP (not exposed by default)
      - "${USULNET_HTTPS_PORT:-7443}:7443"   # HTTPS (auto-TLS, default entry point)
    volumes:
      # Docker socket for container management (required)
      - /var/run/docker.sock:/var/run/docker.sock
      # Persistent application data (backups, PKI certs, license, etc.)
      - usulnet_data:/app/data
      # Trivy vulnerability scanner cache
      - trivy_cache:/var/lib/usulnet/trivy
      # Shared volumes for nginx reverse proxy management
      - nginx_conf:/etc/nginx/conf.d/usulnet
      - nginx_certs:/etc/usulnet/certs
      - acme_webroot:/var/lib/usulnet/acme
    # Host terminal support (nsenter into host PID namespace)
    pid: "host"
    cap_add:
      - SYS_PTRACE    # For host process inspection
      - SYS_ADMIN      # For nsenter into host namespaces
    environment:
      # --- Operation mode ---
      # master: Full usulnet server (default), accepts agent connections
      # agent: Lightweight node connecting to a master
      - USULNET_MODE=${USULNET_MODE:-master}

      # --- Infrastructure connections ---
      # sslmode=require: encrypted connection, no CA cert verification (self-signed default).
      # Override to verify-full if you mount your own CA cert.
      - USULNET_DATABASE_URL=postgres://${DB_USER:-usulnet}:${DB_PASSWORD}@postgres:5432/${DB_NAME:-usulnet}?sslmode=require
      - USULNET_REDIS_URL=rediss://redis:6379
      - USULNET_NATS_URL=natss://nats:4222

      # --- Security (MUST be changed in production) ---
      - USULNET_JWT_SECRET=${JWT_SECRET}
      - USULNET_ENCRYPTION_KEY=${ENCRYPTION_KEY}

      # --- Host terminal (web terminal into the Docker host) ---
      - HOST_TERMINAL_ENABLED=${HOST_TERMINAL_ENABLED:-true}
      - HOST_TERMINAL_USER=${HOST_TERMINAL_USER:-nobody_usulnet}
      - HOST_TERMINAL_SHELL=/bin/bash

      # --- RDP Web Access (Apache Guacamole) ---
      - GUACD_ENABLED=${GUACD_ENABLED:-true}
      - GUACD_HOST=${GUACD_HOST:-guacd}
      - GUACD_PORT=${GUACD_PORT:-4822}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      nats:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: "2.0"
        reservations:
          memory: 256M
          cpus: "0.25"
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"
    networks:
      - usulnet-frontend
      - usulnet-backend

  # ---------------------------------------------------------------------------
  # usulnet Agent — Remote Node (optional, enable with --profile agent)
  # ---------------------------------------------------------------------------
  usulnet-agent:
    image: usulnet/usulnet-agent:${USULNET_VERSION:-latest}
    container_name: usulnet-agent
    restart: unless-stopped
    profiles:
      - agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - agent_data:/app/data
    environment:
      - USULNET_GATEWAY_URL=natss://nats:4222
      - USULNET_AGENT_TOKEN=${AGENT_TOKEN:-change-me}
    depends_on:
      nats:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "test", "-f", "/app/data/agent.pid"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: "0.5"
        reservations:
          memory: 64M
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "3"
    networks:
      - usulnet-backend

  # ---------------------------------------------------------------------------
  # Nginx — Reverse Proxy (managed by usulnet)
  # ---------------------------------------------------------------------------
  nginx:
    image: nginx:1.28-alpine
    container_name: usulnet-nginx
    restart: unless-stopped
    ports:
      - "${NGINX_HTTP_PORT:-80}:80"
      - "${NGINX_HTTPS_PORT:-443}:443"
    volumes:
      - nginx_conf:/etc/nginx/conf.d/usulnet
      - nginx_certs:/etc/usulnet/certs
      - acme_webroot:/var/lib/usulnet/acme
    depends_on:
      usulnet:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "nginx -t 2>/dev/null || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    deploy:
      resources:
        limits:
          memory: 128M
          cpus: "0.5"
        reservations:
          memory: 32M
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "3"
    networks:
      - usulnet-frontend

  # ---------------------------------------------------------------------------
  # Apache Guacamole Daemon — RDP/VNC Web Gateway
  # ---------------------------------------------------------------------------
  guacd:
    image: guacamole/guacd:1.6.0
    container_name: usulnet-guacd
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "nc -z localhost 4822 || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
        reservations:
          memory: 64M
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "3"
    networks:
      - usulnet-frontend

  # ---------------------------------------------------------------------------
  # PostgreSQL 16 — Primary Database
  # ---------------------------------------------------------------------------
  postgres:
    image: postgres:16-alpine
    container_name: usulnet-postgres
    restart: unless-stopped
    # SSL is always enabled. A self-signed ECDSA P-256 cert is generated on
    # every startup — no external files or init containers required.
    # To use your own certificate, uncomment the volume below and place
    # postgres-server.crt / postgres-server.key inside the host directory.
    entrypoint:
      - /bin/sh
      - -c
      - |
        set -e
        mkdir -p /tmp/pg-certs
        if [ -f /certs-src/postgres-server.crt ] && [ -f /certs-src/postgres-server.key ]; then
          cp /certs-src/postgres-server.crt /tmp/pg-certs/server.crt
          cp /certs-src/postgres-server.key /tmp/pg-certs/server.key
        elif command -v openssl >/dev/null 2>&1; then
          openssl req -new -x509 -days 3650 -nodes \
            -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
            -subj "/CN=postgres/O=usulnet" \
            -addext "subjectAltName=DNS:postgres,DNS:localhost,IP:127.0.0.1" \
            -keyout /tmp/pg-certs/server.key \
            -out /tmp/pg-certs/server.crt 2>/dev/null
        else
          echo "ERROR: No TLS certs at /certs-src/ and openssl not available." >&2
          echo "       Mount certs or use a network with internet access." >&2
          exit 1
        fi
        chown 70:70 /tmp/pg-certs/server.key /tmp/pg-certs/server.crt
        chmod 600 /tmp/pg-certs/server.key
        chmod 644 /tmp/pg-certs/server.crt
        exec docker-entrypoint.sh postgres \
          -c ssl=on \
          -c ssl_cert_file=/tmp/pg-certs/server.crt \
          -c ssl_key_file=/tmp/pg-certs/server.key \
          -c shared_buffers=128MB \
          -c work_mem=8MB \
          -c maintenance_work_mem=64MB \
          -c effective_cache_size=256MB \
          -c max_connections=100 \
          -c wal_buffers=4MB \
          -c checkpoint_completion_target=0.9 \
          -c log_min_duration_statement=1000
    environment:
      POSTGRES_USER: ${DB_USER:-usulnet}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME:-usulnet}
      POSTGRES_INITDB_ARGS: "--data-checksums"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ${PG_CERTS_DIR:-./certs}:/certs-src:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-usulnet} -d ${DB_NAME:-usulnet}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
        reservations:
          memory: 128M
    logging:
      driver: json-file
      options:
        max-size: "30m"
        max-file: "3"
    networks:
      - usulnet-backend
    # Port NOT exposed to host by default for security.
    # Access via: docker exec -it usulnet-postgres psql -U usulnet

  # ---------------------------------------------------------------------------
  # Redis 8 — Sessions, Cache & JWT Blacklist (TLS encrypted by default)
  # ---------------------------------------------------------------------------
  redis:
    image: redis:8-alpine
    container_name: usulnet-redis
    restart: unless-stopped
    # TLS is always enabled. A self-signed ECDSA P-256 cert is generated on
    # every startup — no external files or init containers required.
    # To use your own certificate, uncomment the volume below and place
    # redis-server.crt / redis-server.key inside the host directory.
    entrypoint:
      - /bin/sh
      - -c
      - |
        set -e
        mkdir -p /tmp/redis-certs
        if [ -f /certs-src/redis-server.crt ] && [ -f /certs-src/redis-server.key ]; then
          cp /certs-src/redis-server.crt /tmp/redis-certs/server.crt
          cp /certs-src/redis-server.key /tmp/redis-certs/server.key
        elif command -v openssl >/dev/null 2>&1; then
          openssl req -new -x509 -days 3650 -nodes \
            -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
            -subj "/CN=redis/O=usulnet" \
            -addext "subjectAltName=DNS:redis,DNS:localhost,IP:127.0.0.1" \
            -keyout /tmp/redis-certs/server.key \
            -out /tmp/redis-certs/server.crt 2>/dev/null
        else
          echo "ERROR: No TLS certs at /certs-src/ and openssl not available." >&2
          echo "       Mount certs or use a network with internet access." >&2
          exit 1
        fi
        chmod 600 /tmp/redis-certs/server.key
        chmod 644 /tmp/redis-certs/server.crt
        exec redis-server \
          --tls-port 6379 \
          --port 0 \
          --tls-cert-file /tmp/redis-certs/server.crt \
          --tls-key-file /tmp/redis-certs/server.key \
          --tls-auth-clients no \
          --appendonly yes \
          --maxmemory 256mb \
          --maxmemory-policy allkeys-lru \
          --save "60 1000" \
          --tcp-backlog 511
    volumes:
      - redis_data:/data
      - ${REDIS_CERTS_DIR:-./certs}:/certs-src:ro
    healthcheck:
      test: ["CMD", "redis-cli", "--tls", "--insecure", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    deploy:
      resources:
        limits:
          memory: 300M
          cpus: "0.5"
        reservations:
          memory: 64M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - usulnet-backend

  # ---------------------------------------------------------------------------
  # NATS 2.12 — Messaging & Agent Communication (JetStream, TLS)
  # ---------------------------------------------------------------------------
  nats:
    image: nats:2.12-alpine
    container_name: usulnet-nats
    restart: unless-stopped
    ports:
      # Required for remote agent communication in multi-node deployments.
      # Agents on other hosts connect to this port via USULNET_GATEWAY_URL.
      - "${NATS_PORT:-4222}:4222"
    command:
      - "-c"
      - "/etc/nats/nats-server.conf"
    volumes:
      - nats_data:/data
      - ./deploy/nats-server.conf:/etc/nats/nats-server.conf:ro
      - ${NATS_CERTS_DIR:-./certs}:/certs:ro
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8222/healthz"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: "0.5"
        reservations:
          memory: 64M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - usulnet-backend

# =============================================================================
# Volumes — Named and persistent
# =============================================================================
volumes:
  usulnet_data:
    name: usulnet_data
  trivy_cache:
    name: usulnet_trivy_cache
  postgres_data:
    name: usulnet_postgres_data
  redis_data:
    name: usulnet_redis_data
  nats_data:
    name: usulnet_nats_data
  agent_data:
    name: usulnet_agent_data
  nginx_conf:
    name: usulnet_nginx_conf
  nginx_certs:
    name: usulnet_nginx_certs
  acme_webroot:
    name: usulnet_acme_webroot

# =============================================================================
# Networks — Isolated backend and frontend
# =============================================================================
networks:
  # Backend network: PostgreSQL, Redis, NATS (not exposed to host)
  usulnet-backend:
    name: usulnet-backend
    driver: bridge
    internal: true
  # Frontend network: usulnet app, guacd (web-facing services)
  usulnet-frontend:
    name: usulnet-frontend
    driver: bridge