eddie/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

feat(komodo): Add Docker and server management platform

Browse source 
Add Komodo for centralized Docker container and server management.

Features:
- Docker container deployment and management
- Server monitoring and resource tracking
- Build system for Docker images from Git repositories
- Multi-server support with periphery agents
- Webhooks for automatic deployments

Stack includes:
- Komodo Core (web UI and API)
- Komodo Periphery (local Docker agent)
- MongoDB (configuration storage)

Includes comprehensive configuration with:
- Pre-configured .env with all available options
- Optional TOML config files for advanced settings
- Setup script with pre-deployment validation
- Full documentation and security checklist
This commit is contained in:
Eduardo Figueroa 2025-12-04 18:44:14 +00:00
parent 60781182f6
commit 27e4f5267d
5 changed files with 566 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
compose/services/komodo/.env.example Normal file
View file

@ -0,0 +1,35 @@
# Komodo Environment Configuration
# Copy this file to .env and customize for your deployment
# Version
KOMODO_VERSION=latest
# Database (CHANGE THESE!)
KOMODO_DB_USERNAME=admin
KOMODO_DB_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
# Authentication (CHANGE THIS!)
KOMODO_PASSKEY=CHANGE_ME_TO_STRONG_RANDOM_STRING
# Core Settings
KOMODO_TITLE=Komodo
KOMODO_HOST=https://komodo.fig.systems
TZ=America/Los_Angeles
# User Management
KOMODO_LOCAL_AUTH=true
KOMODO_ENABLE_NEW_USERS=true
KOMODO_FIRST_SERVER_ADMIN=true
# Monitoring
KOMODO_MONITORING_INTERVAL=15-sec
# Logging
KOMODO_LOGGING_LEVEL=info
PERIPHERY_LOGGING_LEVEL=info
# Periphery Settings
PERIPHERY_ROOT_DIR=/etc/komodo
PERIPHERY_HTTPS_ENABLED=true
PERIPHERY_DISABLE_TERMINALS=false
PERIPHERY_INCLUDE_DISK_MOUNTS=/

18
compose/services/komodo/.gitignore vendored Normal file
View file

@ -0,0 +1,18 @@
# Sensitive configuration
.env
# Data directories
data/
backups/
# MongoDB volumes (if using bind mounts)
mongo-data/
mongo-config/
# Logs
*.log
# Certificates
*.pem
*.key
*.crt

286
compose/services/komodo/README.md Normal file
View file

@ -0,0 +1,286 @@
# 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:
```bash
# 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
```bash
# Create the periphery root directory on the host
sudo mkdir -p /etc/komodo
sudo chown -R $USER:$USER /etc/komodo
```
### 3. Deploy
```bash
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`:
```bash
# 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)
```bash
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:
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
KOMODO_LOGGING_LEVEL=info # off, error, warn, info, debug, trace
PERIPHERY_LOGGING_LEVEL=info
```
### OpenTelemetry
For distributed tracing:
```bash
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:
```bash
KOMODO_PRUNE_INTERVAL=1-day
KOMODO_KEEP_STATS_FOR_DAYS=30
KOMODO_KEEP_ALERTS_FOR_DAYS=90
```
## Troubleshooting
### Check Logs
```bash
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:
```bash
# In .env, ensure these match:
KOMODO_PASSKEY=abc123
```
### Reset Admin Password
Connect to MongoDB and reset user:
```bash
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
```bash
# 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:
```bash
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.

138
compose/services/komodo/compose.yaml Normal file
View file

@ -0,0 +1,138 @@
# Komodo - Docker & Server Management Platform
# Docs: https://komo.do/docs/
# GitHub: https://github.com/moghtech/komodo
services:
komodo-mongo:
container_name: komodo-mongo
image: mongo:8.0
restart: unless-stopped
command: ["--wiredTigerCacheSizeGB", "0.25"]
environment:
MONGO_INITDB_ROOT_USERNAME: ${KOMODO_DB_USERNAME:-admin}
MONGO_INITDB_ROOT_PASSWORD: ${KOMODO_DB_PASSWORD:-admin}
volumes:
- mongo-data:/data/db
- mongo-config:/data/configdb
networks:
- homelab
labels:
# Skip this container from Komodo management
komodo.skip: true
komodo-core:
container_name: komodo-core
image: ghcr.io/moghtech/komodo-core:${KOMODO_VERSION:-latest}
restart: unless-stopped
depends_on:
- komodo-mongo
env_file:
- .env
environment:
# Database Configuration
KOMODO_DATABASE_URI: mongodb://${KOMODO_DB_USERNAME:-admin}:${KOMODO_DB_PASSWORD:-admin}@komodo-mongo:27017
# Core Settings
KOMODO_TITLE: ${KOMODO_TITLE:-Komodo}
KOMODO_HOST: ${KOMODO_HOST:-https://komodo.fig.systems}
KOMODO_PORT: 9120
# Authentication
KOMODO_PASSKEY: ${KOMODO_PASSKEY:-abc123}
KOMODO_LOCAL_AUTH: ${KOMODO_LOCAL_AUTH:-true}
KOMODO_ENABLE_NEW_USERS: ${KOMODO_ENABLE_NEW_USERS:-true}
KOMODO_ENABLE_NEW_USER_WEBHOOK: ${KOMODO_ENABLE_NEW_USER_WEBHOOK:-false}
# Monitoring
KOMODO_MONITORING_INTERVAL: ${KOMODO_MONITORING_INTERVAL:-15-sec}
# Logging
KOMODO_LOGGING_LEVEL: ${KOMODO_LOGGING_LEVEL:-info}
TZ: ${TZ:-America/Los_Angeles}
volumes:
- ./data:/data
- ./backups:/backups
# Optional: mount custom config
# - ./config/core.config.toml:/config/core.config.toml:ro
networks:
- homelab
labels:
# Skip this container from Komodo management
komodo.skip: true
# Traefik
traefik.enable: true
traefik.docker.network: homelab
# Web UI
traefik.http.routers.komodo.rule: Host(`komodo.fig.systems`)
traefik.http.routers.komodo.entrypoints: websecure
traefik.http.routers.komodo.tls.certresolver: letsencrypt
traefik.http.services.komodo.loadbalancer.server.port: 9120
# Optional: SSO Protection
# traefik.http.routers.komodo.middlewares: tinyauth
komodo-periphery:
container_name: komodo-periphery
image: ghcr.io/moghtech/komodo-periphery:${KOMODO_VERSION:-latest}
restart: unless-stopped
depends_on:
- komodo-core
env_file:
- .env
environment:
# Core Settings
PERIPHERY_ROOT_DIR: ${PERIPHERY_ROOT_DIR:-/etc/komodo}
PERIPHERY_PORT: 8120
# Authentication
PERIPHERY_PASSKEY: ${KOMODO_PASSKEY:-abc123}
PERIPHERY_HTTPS_ENABLED: ${PERIPHERY_HTTPS_ENABLED:-true}
# Features
PERIPHERY_DISABLE_TERMINALS: ${PERIPHERY_DISABLE_TERMINALS:-false}
# Disk Monitoring
PERIPHERY_INCLUDE_DISK_MOUNTS: ${PERIPHERY_INCLUDE_DISK_MOUNTS:-/}
# PERIPHERY_EXCLUDE_DISK_MOUNTS: /snap,/boot
# Logging
PERIPHERY_LOGGING_LEVEL: ${PERIPHERY_LOGGING_LEVEL:-info}
TZ: ${TZ:-America/Los_Angeles}
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /proc:/proc:ro
- ${PERIPHERY_ROOT_DIR:-/etc/komodo}:${PERIPHERY_ROOT_DIR:-/etc/komodo}
# Optional: mount custom config
# - ./config/periphery.config.toml:/config/periphery.config.toml:ro
networks:
- homelab
labels:
# Skip this container from Komodo management
komodo.skip: true
volumes:
mongo-data:
mongo-config:
networks:
homelab:
external: true

89
compose/services/komodo/setup.sh Executable file
View file

@ -0,0 +1,89 @@
#!/bin/bash
# Komodo Setup Script
set -e
echo "==================================="
echo "Komodo Setup"
echo "==================================="
echo ""
# Check if running as root
if [ "$EUID" -eq 0 ]; then
echo "Please do not run as root"
exit 1
fi
# Create periphery root directory
echo "Creating periphery root directory..."
sudo mkdir -p /etc/komodo
sudo chown -R $USER:$USER /etc/komodo
echo "✓ Created /etc/komodo"
echo ""
# Check if .env exists
if [ ! -f .env ]; then
echo "Error: .env file not found!"
echo "Please copy .env.example to .env and configure it first."
exit 1
fi
# Check for default passwords
echo "Checking for default passwords..."
if grep -q "KOMODO_DB_PASSWORD=admin" .env; then
echo "⚠️ WARNING: Default database password detected!"
echo " Please update KOMODO_DB_PASSWORD in .env before deployment."
fi
if grep -q "KOMODO_PASSKEY=abc123" .env; then
echo "⚠️ WARNING: Default passkey detected!"
echo " Please update KOMODO_PASSKEY in .env before deployment."
fi
echo ""
echo "==================================="
echo "Pre-deployment Checklist"
echo "==================================="
echo ""
echo "Before deploying, ensure you have:"
echo " [ ] Updated KOMODO_DB_PASSWORD to a strong password"
echo " [ ] Updated KOMODO_PASSKEY to a strong random string"
echo " [ ] Updated KOMODO_HOST to your domain"
echo " [ ] Configured TZ (timezone)"
echo " [ ] Reviewed KOMODO_ENABLE_NEW_USERS setting"
echo ""
read -p "Have you completed the checklist above? (y/N) " -n 1 -r
echo ""
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
echo "Please complete the checklist and run this script again."
exit 1
fi
echo ""
echo "==================================="
echo "Deploying Komodo..."
echo "==================================="
echo ""
# Deploy
docker compose up -d
echo ""
echo "==================================="
echo "Deployment Complete!"
echo "==================================="
echo ""
echo "Access Komodo at: https://komodo.fig.systems"
echo ""
echo "First-time setup:"
echo " 1. Open the URL above"
echo " 2. Create your admin account"
echo " 3. Configure servers and resources"
echo ""
echo "To view logs:"
echo " docker compose logs -f"
echo ""
echo "To stop:"
echo " docker compose down"
echo ""