Komodo Deployment — Reference

Installed: 2026-07-09 on Core (netcup RS 2000) Version: Komodo v2.2.0 Purpose: Multi-host Docker management across ITPP servers (Core, ai, docker, unms, etc.) Architecture: Core (web UI + API server, port 9120) + MongoDB → Periphery agents on each managed host

Directory Structure

/root/docker/komodo/
├── docker-compose.yml      # Core + MongoDB
├── data/
│   ├── mongo-data/         # MongoDB persistent storage
│   └── mongo-config/       # MongoDB config
├── backups/                # Database backups
└── keys/
    ├── core.key            # Core private key (auto-generated)
    └── core.pub            # Core public key (auto-generated)

Docker Compose (Core)

services:
  mongo:
    image: mongo
    restart: unless-stopped
    command: --quiet --wiredTigerCacheSizeGB 0.25
    volumes:
      - ./data/mongo-data:/data/db
      - ./data/mongo-config:/data/configdb
    networks:
      - komodo-net
    deploy:
      resources:
        limits:
          memory: 1G

  core:
    image: ghcr.io/moghtech/komodo-core:2
    init: true
    restart: unless-stopped
    ports:
      - 9120:9120
    depends_on:
      - mongo
    volumes:
      - ./backups:/backups
      - ./keys:/config/keys
    environment:
      # Database
      - KOMODO_DATABASE_ADDRESS=mongo:27017
      # Server
      - KOMODO_PORT=9120
      - KOMODO_HOST=https://komodo.itpropartner.com
      - KOMODO_TITLE=Komodo
      # Auth
      - KOMODO_LOCAL_AUTH=true
      - KOMODO_INIT_ADMIN_USERNAME=admin
      - KOMODO_INIT_ADMIN_PASSWORD=changeme
      # First server (this host)
      - KOMODO_FIRST_SERVER_NAME=core
      # Periphery auth
      - KOMODO_PERIPHERY_PUBLIC_KEY=file:/config/keys/periphery.pub
      # Secrets
      - KOMODO_WEBHOOK_SECRET=komodo-webhook-secret
      - KOMODO_JWT_SECRET=komodo-jwt-secret-change-me
      - KOMODO_JWT_TTL=1-day
      # Monitoring
      - KOMODO_MONITORING_INTERVAL=15-sec
      - KOMODO_RESOURCE_POLL_INTERVAL=1-hr
      # UI
      - KOMODO_DISABLE_CONFIRM_DIALOG=false
      - KOMODO_TRANSPARENT_MODE=false
    networks:
      - komodo-net
    deploy:
      resources:
        limits:
          memory: 512M

networks:
  komodo-net:
    driver: bridge

Critical Env Variable Pitfalls (V2)

Do NOT use MONGO_CONNECTION_STRING — Komodo v2 uses KOMODO_DATABASE_ADDRESS=mongo:27017
Do NOT use KOMODO_SERVER_PORT — use KOMODO_PORT=9120
Do NOT use KOMODO_SERVER_HOST — use KOMODO_BIND_IP=[::] (default)
KOMODO_PERIPHERY_PUBLIC_KEY must be set with file:/config/keys/periphery.pub for auto-generation
init: true is essential on the core container (handles PID 1 zombie reaping properly)
KOMODO_HOST must be set to the URL users will access (used for OAuth redirects, webhook suggestions)

Startup Log Verification

Successful startup shows:

Server starting on http://[::]:9120
Creating init admin user...
Successfully created init admin user.
Creating initial system resources...

The admin user is created on first launch only. Core v2.2.0 auto-creates starting resources: "Backup Core Database" procedure and "Global Auto Update" procedure.

# Get JWT token
curl -s -X POST http://127.0.0.1:9120/auth/login \
  -H "Content-Type: application/json" \
  -d '{"type":"Local","username":"admin","password":"changeme"}'

Note: the login body requires "type":"Local" — missing this field returns: "Failed to deserialize the JSON body into the target type: missing field type"

Onboarding Key

The onboarding key is available in the Komodo web UI after login:

Go to the Servers page
Click Add Server / Onboard
Copy the onboarding key (starts with O-)

Or retrieve via the API with a valid JWT:

curl -s http://127.0.0.1:9120/api/core -H "Authorization: Bearer <token>"
# Extract onboarding_key from response

Periphery Installation (on each managed host)

# Via systemd script (recommended for production)
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://komodo.itpropartner.com" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

The Periphery agent communicates with Core via WebSocket. It listens on port 8120 by default. The agent runs as a systemd service when installed via the Python script.

Docker Periphery (alternative, for containers)

services:
  periphery:
    image: ghcr.io/moghtech/komodo-periphery:2
    init: true
    restart: unless-stopped
    depends_on:
      - core
    env_file: ./compose.env
    volumes:
      - keys:/config/keys
      - /var/run/docker.sock:/var/run/docker.sock
      - /proc:/proc
      - ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}

Public Key Authentication

Core uses Noise protocol key pairs for Periphery authentication.

Core keys auto-generated at: /config/keys/core.key and /config/keys/core.pub
Periphery public key expected at: /config/keys/periphery.pub (auto-generated if KOMODO_PERIPHERY_PUBLIC_KEY is set and file doesn't exist)
Example public key: -----BEGIN PUBLIC KEY-----\nMCowBQYDK2VuAyEAo+xXlRx+KcxbFkscAx3JcmGKudDwoID3AkGnzjFb1AE=\n-----END PUBLIC KEY-----

5.3 KiB Raw Blame History