homelab/compose/services/komodo

Komodo - Docker & Server Management Platform

Komodo is a comprehensive platform for managing Docker containers, servers, and deployments with a modern web interface.

Features

• Docker Management: Deploy and manage Docker containers and compose stacks
• Server Monitoring: Track server health, resources, and statistics
• Build System: Build Docker images from Git repositories
• Multi-Server: Manage multiple servers from a single interface
• Webhooks: Automatic deployments from git webhooks
• Resource Management: Organize with tags, descriptions, and search
• Authentication: Local auth, OAuth (GitHub, Google), and OIDC support

Quick Start

1. Update Environment Variables

Edit .env and update these critical values:

# Database Password
KOMODO_DB_PASSWORD=your-strong-password-here

# Shared Passkey (Core <-> Periphery authentication)
KOMODO_PASSKEY=your-strong-random-string-here

# Host URL (update to your domain)
KOMODO_HOST=https://komodo.fig.systems

# Timezone
TZ=America/Los_Angeles

2. Create Required Directory

# Create the periphery root directory on the host
sudo mkdir -p /etc/komodo
sudo chown -R $USER:$USER /etc/komodo

3. Deploy

docker compose up -d

4. Access

Open https://komodo.fig.systems and create your first admin account.

Architecture

The stack consists of three services:

1. komodo-mongo: MongoDB database for storing configuration
2. komodo-core: Main web interface and API (port 9120)
3. komodo-periphery: Local agent for Docker/server management (port 8120)

Configuration

Environment Variables (.env)

The .env file contains all primary configuration. Key sections:

• Database: MongoDB credentials
• Authentication: Passkey, local auth, OAuth providers
• Monitoring: Polling intervals and logging
• Periphery: Root directory, SSL, terminal access
• Integrations: Git providers, Docker registries, AWS

TOML Configuration Files (Optional)

For advanced configuration, mount TOML files:

• config/core.config.toml → /config/core.config.toml
• config/periphery.config.toml → /config/periphery.config.toml

Uncomment the volume mounts in compose.yaml to use these files.

Security Checklist

Before deploying to production:

• Change KOMODO_DB_PASSWORD to a strong password
• Change KOMODO_PASSKEY to a strong random string (32+ characters)
• Review KOMODO_ENABLE_NEW_USERS - set to false after creating admin
• Consider enabling SSO via Traefik middleware (see compose.yaml)
• Set PERIPHERY_DISABLE_TERMINALS=true if shell access not needed
• Configure PERIPHERY_ALLOWED_IPS to restrict access by IP
• Review disk mount monitoring in PERIPHERY_INCLUDE_DISK_MOUNTS
• Enable proper SSL certificates (auto-generated by Traefik)
• Set up OAuth providers (GitHub/Google) or OIDC for SSO

Authentication Options

Local Authentication (Default)

Username/password authentication. First user becomes admin.

OAuth Providers

Configure in .env:

# GitHub OAuth
KOMODO_GITHUB_OAUTH_ENABLED=true
KOMODO_GITHUB_OAUTH_ID=your-oauth-id
KOMODO_GITHUB_OAUTH_SECRET=your-oauth-secret

# Google OAuth
KOMODO_GOOGLE_OAUTH_ENABLED=true
KOMODO_GOOGLE_OAUTH_ID=your-oauth-id
KOMODO_GOOGLE_OAUTH_SECRET=your-oauth-secret

OIDC (e.g., Keycloak, Auth0)

KOMODO_OIDC_ENABLED=true
KOMODO_OIDC_PROVIDER=https://your-oidc-provider.com
KOMODO_OIDC_CLIENT_ID=your-client-id
KOMODO_OIDC_CLIENT_SECRET=your-client-secret

Integrations

Git Provider Access

For private repositories, configure credentials:

# GitHub
KOMODO_GIT_GITHUB_ACCOUNTS=personal
KOMODO_GIT_GITHUB_PERSONAL_USERNAME=your-username
KOMODO_GIT_GITHUB_PERSONAL_TOKEN=ghp_your-token

# Gitea/Self-hosted
KOMODO_GIT_GITEA_ACCOUNTS=homelab
KOMODO_GIT_GITEA_HOMELAB_DOMAIN=git.example.com
KOMODO_GIT_GITEA_HOMELAB_USERNAME=your-username
KOMODO_GIT_GITEA_HOMELAB_TOKEN=your-token

Docker Registry Access

For private registries:

# Docker Hub
KOMODO_REGISTRY_DOCKERHUB_ACCOUNTS=personal
KOMODO_REGISTRY_DOCKERHUB_PERSONAL_USERNAME=your-username
KOMODO_REGISTRY_DOCKERHUB_PERSONAL_PASSWORD=your-password

# Custom Registry
KOMODO_REGISTRY_CUSTOM_ACCOUNTS=homelab
KOMODO_REGISTRY_CUSTOM_HOMELAB_DOMAIN=registry.example.com
KOMODO_REGISTRY_CUSTOM_HOMELAB_USERNAME=your-username
KOMODO_REGISTRY_CUSTOM_HOMELAB_PASSWORD=your-password

Multi-Server Setup

To manage additional servers:

1. Deploy komodo-periphery on each server
2. Configure with the same KOMODO_PASSKEY
3. Expose port 8120 (with SSL enabled)
4. Add server in Komodo Core UI with periphery URL

Monitoring & Logging

Adjust Polling Intervals

# Server health checks
KOMODO_MONITORING_INTERVAL=15-sec

# System stats
PERIPHERY_STATS_POLLING_RATE=5-sec

# Container stats
PERIPHERY_CONTAINER_STATS_POLLING_RATE=30-sec

Log Levels

KOMODO_LOGGING_LEVEL=info  # off, error, warn, info, debug, trace
PERIPHERY_LOGGING_LEVEL=info

OpenTelemetry

For distributed tracing:

KOMODO_LOGGING_OTLP_ENDPOINT=http://your-otlp-collector:4317
PERIPHERY_LOGGING_OTLP_ENDPOINT=http://your-otlp-collector:4317

Data Management

Backups

MongoDB data is persisted in Docker volumes:

• mongo-data: Database files
• mongo-config: Configuration

The ./backups directory is mounted for storing backup exports.

Data Pruning

Automatically clean old data:

KOMODO_PRUNE_INTERVAL=1-day
KOMODO_KEEP_STATS_FOR_DAYS=30
KOMODO_KEEP_ALERTS_FOR_DAYS=90

Troubleshooting

Check Logs

docker compose logs -f komodo-core
docker compose logs -f komodo-periphery
docker compose logs -f komodo-mongo

Verify Passkey Match

Core and Periphery must share the same passkey:

# In .env, ensure these match:
KOMODO_PASSKEY=abc123

Reset Admin Password

Connect to MongoDB and reset user:

docker exec -it komodo-mongo mongosh -u admin -p admin
use komodo
db.users.updateOne({username: "admin"}, {$set: {password: "new-hashed-password"}})

Check Periphery Connection

In Komodo Core UI, add a server pointing to:

• URL: http://komodo-periphery:8120 (internal)
• Or: https://komodo.fig.systems:8120 (if externally accessible)
• Passkey: Must match KOMODO_PASSKEY

Upgrading

# Pull latest images
docker compose pull

# Recreate containers
docker compose up -d

# Check logs
docker compose logs -f

Note: Pin specific versions in .env for production:

KOMODO_VERSION=v1.2.3

Links

• Documentation: https://komo.do/docs/
• GitHub: https://github.com/moghtech/komodo
• Discord: https://discord.gg/komodo

License

Komodo is open source under the GPL-3.0 license.