Managing Docker Across Multiple Servers with Komodo

1. Deploy Komodo Core

Create a project directory on your management server:

mkdir -p ~/komodo
cd ~/komodo

Create compose.yaml

This runs MongoDB and Komodo Core:

services:
  mongo:
    image: mongo
    labels:
      komodo.skip: # Prevents Komodo's StopAllContainers from shutting itself down
    command: --quiet --wiredTigerCacheSizeGB 0.25
    restart: unless-stopped
    networks:
      - komodo-net
    volumes:
      - ./data/mongo-data:/data/db
      - ./config/mongo-config:/data/configdb
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${KOMODO_DB_USERNAME}
      MONGO_INITDB_ROOT_PASSWORD: ${KOMODO_DB_PASSWORD}

  core:
    image: ghcr.io/moghtech/komodo-core:${COMPOSE_KOMODO_IMAGE_TAG:-latest}
    labels:
      komodo.skip: # Prevents Komodo's StopAllContainers from shutting itself down
    restart: unless-stopped
    depends_on:
      - mongo
    ports:
      - 9120:9120
    networks:
      - komodo-net
    env_file: .env
    environment:
      KOMODO_DATABASE_ADDRESS: mongo:27017
      KOMODO_DATABASE_USERNAME: ${KOMODO_DB_USERNAME}
      KOMODO_DATABASE_PASSWORD: ${KOMODO_DB_PASSWORD}
    volumes:
      - ${COMPOSE_KOMODO_BACKUPS_PATH:-./backups}:/backups

networks:
  komodo-net:

--wiredTigerCacheSizeGB 0.25 caps MongoDB’s RAM at 250 MB. The komodo.skip label prevents Komodo from shutting down its own containers when you trigger “Stop All Containers”.

Create .env

## Image version
COMPOSE_KOMODO_IMAGE_TAG=latest

## Database backups path
COMPOSE_KOMODO_BACKUPS_PATH=./backups

## Database credentials
KOMODO_DB_USERNAME=komodo
KOMODO_DB_PASSWORD=<generate-a-strong-password>

## Passkey for Core ↔ Periphery authentication
KOMODO_PASSKEY=<generate-a-random-passkey>

## Your timezone (for scheduled tasks)
TZ=Europe/Bucharest

## Public URL of your Komodo instance
KOMODO_HOST=https://komodo.example.com
KOMODO_TITLE=Komodo

## Monitoring intervals
KOMODO_MONITORING_INTERVAL=15-sec
KOMODO_RESOURCE_POLL_INTERVAL=1-hr

## Secrets for webhooks and JWT tokens
KOMODO_WEBHOOK_SECRET=<generate-a-random-secret>
KOMODO_JWT_SECRET=<generate-a-random-jwt-secret>
KOMODO_JWT_TTL=1-day

## Local auth (username + password login)
KOMODO_LOCAL_AUTH=true
KOMODO_INIT_ADMIN_USERNAME=admin
KOMODO_INIT_ADMIN_PASSWORD=<your-admin-password>
KOMODO_DISABLE_USER_REGISTRATION=false
KOMODO_ENABLE_NEW_USERS=false

Start Komodo Core

cd ~/komodo
sudo docker compose up -d

Verify everything is running:

sudo docker compose ps
sudo docker compose logs --tail=50 core

You should see Core listening on port 9120. Open http://<your-server-ip>:9120 in your browser and log in with the admin credentials from your .env.

2. Install Periphery on remote servers (and to the core server if you plan on deploying stacks there too)

Periphery is the lightweight agent that gives Komodo Core control over Docker on a remote host. The recommended approach is running it as a systemd service directly on the host (not in a container), since it needs full access to the host’s Docker daemon.

Run these commands on each remote server you want to manage:

# Switch to root
sudo su -

# Download and install Periphery
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | python3

# Enable and start the service
systemctl enable periphery
systemctl start periphery

# Verify it's running
systemctl status periphery

# Exit root shell
exit

The setup script detects your system architecture, downloads the appropriate binary, creates the systemd unit file, and generates a default config at /etc/komodo/periphery.config.toml.

Container-based Periphery Advanced

You can also run Periphery as a Docker container (see the Komodo compose examples), but the systemd approach is recommended. Running on the host gives Periphery direct access to the Docker socket without additional volume mount complexity, and avoids the chicken-and-egg problem of managing a container manager from inside a container.

3. Configure Periphery

Edit the Periphery configuration on each remote server:

sudo nano /etc/komodo/periphery.config.toml

The key settings to adjust are the directories where Periphery manages resources:

## Base directory for Periphery's managed resources
root_directory = "/opt/komodo"

## Where Periphery clones Git repositories
repo_dir = "/opt/komodo/repos"

## Where Periphery manages Docker Compose stacks
stack_dir = "/opt/komodo/stacks"

Make sure the directories exist and are writable:

sudo mkdir -p /opt/komodo/repos /opt/komodo/stacks

Restrict access to Periphery Important

By default, Periphery listens on port 8120 and accepts connections from any IP. In production, you should restrict this to only your Komodo Core server.

Option A: Firewall rules (recommended)

# Allow only your Komodo Core server's IP
sudo ufw allow from <core-server-ip> to any port 8120
sudo ufw deny 8120

Option B: Periphery config allowlist

Add to periphery.config.toml:

allowed_ips = ["<core-server-ip>"]

Apply your changes:

sudo systemctl restart periphery

4. Connect servers in Komodo

1. Open the Komodo web UI (the URL from Step 1)
2. Navigate to Servers in the sidebar
3. Click New Server
4. Give it a descriptive name (e.g. docker-host-01)
5. Set the server address:

https://<remote-server-ip>:8120

https://host.docker.internal:8120

extra_hosts:
  - host.docker.internal:host-gateway

6. Save the server configuration

If the connection fails, check that:

• The KOMODO_PASSKEY in your Core .env matches what Periphery expects (the default passkey is empty — if you set one in Core, you need to set the same in periphery.config.toml)
• Port 8120 is reachable from the Core server
• The Periphery service is running (systemctl status periphery)

Once connected, Komodo shows the server’s system stats and running containers.

5. Deploy your first stack

Quick test — deploy a simple container through Komodo to verify everything works.

1. In the Komodo dashboard, navigate to Stacks
2. Click New Stack
3. Name it whoami-test
4. Select your remote server from the target dropdown
5. Paste this Compose definition:

services:
  whoami:
    image: traefik/whoami:latest
    ports:
      - "8080:80"
    restart: unless-stopped

6. Click Deploy

Komodo sends the definition to the Periphery agent, which runs docker compose up -d on the remote server.

Verify by visiting http://<remote-server-ip>:8080 — you should see the whoami response with hostname, IP, and request headers.

To clean up the test: in the Komodo dashboard, click the whoami-test stack, then Destroy to remove both the containers and the stack definition. You can then delete the stack.