homelab/compose/services/komodo/README.md

# 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.