Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/komodo

komodo

Flagged

references/komodo.md

View on GitHub
# Komodo Infrastructure Management Skill

## Description
Expert assistant for Komodo (komo.do) - an open-source Docker infrastructure management platform. This skill provides comprehensive support for deploying, managing, and automating containerized applications using Komodo's Core/Periphery architecture.

## Skill Scope

### What This Skill Covers
- Komodo resource configuration (Stacks, Deployments, Builds, Procedures, Actions)
- Docker Compose stack deployment via Komodo
- Build automation and CI/CD workflows
- GitOps with Resource Sync
- Infrastructure monitoring and alerting
- Komodo API and TypeScript SDK usage
- CLI (`km`) command usage
- Automation with Procedures and Actions
- Multi-server orchestration
- Security and access control configuration

### When to Use This Skill
- Deploying containerized applications with Komodo
- Creating or modifying Komodo resource configurations
- Setting up GitOps workflows with Resource Sync
- Automating infrastructure tasks with Procedures and Actions
- Troubleshooting Komodo deployments
- Configuring monitoring and alerts
- Managing multi-server Docker infrastructure
- Converting existing Docker setups to Komodo

## Core Concepts

### Architecture
Komodo uses a two-component architecture:
- **Core**: Central server with REST/WebSocket API and web UI (port 9120)
- **Periphery**: Lightweight agents on managed servers (port 8120)
- Communication: Core → Periphery (unidirectional initiation)
- Authentication: Passkey-based (KOMODO_PASSKEY = PERIPHERY_PASSKEY)

### Resource Types
All resources in Komodo share common traits:
- Unique name and ID
- Tagging for organization
- Permission controls
- Audit logging

**Primary Resources:**
1. **Server**: Connection to Periphery agent with monitoring
2. **Deployment**: Single Docker container deployment
3. **Stack**: Docker Compose project (UI, Host, or Git-based)
4. **Build**: Automated Docker image builds from Git
5. **Builder**: Build capacity (Server or AWS instances)
6. **Repo**: Git repository for script execution
7. **Procedure**: Multi-stage orchestration (parallel + sequential)
8. **Action**: TypeScript automation with full API access
9. **Resource Sync**: GitOps declarative infrastructure
10. **Alerter**: Notification routing system
11. **Template**: Reusable resource configurations

## Common Tasks

### Task 1: Create Docker Compose Stack from Git

**Context:** Deploy a Docker Compose application stored in Git with auto-deployment on push.

**Steps:**
1. Identify Stack configuration requirements:
   - Git repository URL and branch
   - Environment variables needed
   - Target Server for deployment
   - Docker registry accounts (if using private images)

2. Create Resource Sync TOML configuration:
```toml
[[stack]]
name = "my-application"
description = "My application stack deployed from Git"

[stack.config]
server = "main-server"
repo = "username/my-app-repo"
git_account = "github-account"
branch = "main"
file_paths = ["docker-compose.yml"]

[stack.config.environment]
NODE_ENV = "production"
APP_VERSION = "${APP_VERSION}"
DB_PASSWORD = "${DB_PASSWORD}"
API_KEY = "${API_KEY}"

[[stack.config.labels]]
environment = "production"
app = "my-application"
```

3. Configure webhook for auto-deployment:
   - Get webhook URL from Komodo Stack resource
   - Add to Git provider (GitHub/GitLab/Gitea)
   - Set content type: application/json
   - Configure webhook secret

4. Verify deployment:
   - Check Stack status in Komodo UI
   - Monitor container logs
   - Verify health checks

**Best Practices:**
- Use Git-based Stacks for version control
- Store secrets in Komodo Core config, not in compose files
- Use variable interpolation: `${VARIABLE_NAME}`
- Enable "Poll for Updates" to review changes before auto-deploy
- Use monorepo structure for multiple related stacks

### Task 2: Create Multi-Stage Deployment Procedure

**Context:** Orchestrate updates across multiple services with proper sequencing.

**Steps:**
1. Identify deployment stages and dependencies:
   - Which repos need to be pulled
   - Which builds need to run
   - Which stacks depend on which builds
   - What cleanup is needed

2. Create Procedure TOML configuration:
```toml
[[procedure]]
name = "deploy-full-stack"
description = "Deploy all services in correct order"

# Stage 1: Pull all repositories (parallel)
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "PullRepo"
params = { repo = "frontend-repo" }

[[procedure.config.stages.executions]]
operation = "PullRepo"
params = { repo = "backend-repo" }

[[procedure.config.stages.executions]]
operation = "PullRepo"
params = { repo = "api-repo" }

# Stage 2: Build all images (parallel, waits for Stage 1)
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "RunBuild"
params = { build = "frontend-build" }

[[procedure.config.stages.executions]]
operation = "RunBuild"
params = { build = "backend-build" }

[[procedure.config.stages.executions]]
operation = "RunBuild"
params = { build = "api-build" }

# Stage 3: Deploy stacks (parallel, waits for Stage 2)
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "DeployStack"
params = { stack = "frontend-stack" }

[[procedure.config.stages.executions]]
operation = "DeployStack"
params = { stack = "backend-stack" }

[[procedure.config.stages.executions]]
operation = "DeployStack"
params = { stack = "api-stack" }

# Stage 4: Cleanup (waits for Stage 3)
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "PruneSystem"
params = { server = "main-server" }
```

3. Configure triggering:
   - Manual: Button in Komodo UI
   - Webhook: For CI/CD integration
   - Scheduled: Cron format for regular updates
   - Run-on-startup: For initialization

4. Test execution:
   - Run procedure manually first
   - Monitor stage completion
   - Check logs for errors
   - Verify all stacks deployed correctly

**Best Practices:**
- Group independent operations in same stage (parallel execution)
- Order stages by dependencies (sequential execution)
- Add cleanup stage at the end
- Use BatchDeployStackIfChanged for conditional updates
- Monitor procedure execution logs

### Task 3: Create TypeScript Action for Complex Automation

**Context:** Implement custom automation logic beyond Procedure capabilities.

**Steps:**
1. Identify automation requirements:
   - What resources need to be queried
   - What operations need to be performed
   - What conditions determine actions
   - What parameters should be configurable

2. Create Action TypeScript script:
```typescript
// Action: sync-environment-branches
// Description: Sync all stacks to match a target branch

// ARGS.branch is passed via webhook or manual execution
const targetBranch = ARGS.branch || "main";
const dryRun = ARGS.dryRun || false;

// Pre-initialized 'komodo' client available
const stacks = await komodo.read("ListStacks", {});

const updates = [];

for (const stack of stacks) {
  const config = await komodo.read("GetStack", { stack: stack.name });

  // Only update Git-based stacks
  if (config.config.repo && config.config.branch !== targetBranch) {
    updates.push({
      name: stack.name,
      oldBranch: config.config.branch,
      newBranch: targetBranch
    });

    if (!dryRun) {
      await komodo.write("UpdateStack", {
        name: stack.name,
        config: {
          ...config.config,
          branch: targetBranch
        }
      });

      // Deploy with new branch
      await komodo.execute("DeployStack", { stack: stack.name });
    }
  }
}

// Return summary
return {
  message: dryRun ? "Dry run completed" : "Branch sync completed",
  updatedStacks: updates.length,
  updates: updates
};
```

3. Create Action resource configuration:
```toml
[[action]]
name = "sync-environment-branches"
description = "Sync all stack branches to target environment"

[action.config]
# TypeScript code goes in Komodo UI editor

# Default arguments
[action.config.args]
branch = "main"
dryRun = false
```

4. Configure triggering and testing:
   - Test with dryRun=true first
   - Configure webhook for Git events
   - Use RunAction via API or CLI
   - Enable run-on-startup if needed (v1.19.0+)

**Best Practices:**
- Use ARGS for configurable parameters
- Provide sensible defaults
- Implement dry-run mode for testing
- Return useful summary information
- Use type-safe operations (TypeScript inference)
- Handle errors gracefully
- Log important actions for audit trail

### Task 4: Set Up GitOps with Resource Sync

**Context:** Manage all infrastructure as code using Git repository.

**Steps:**
1. Create infrastructure repository structure:
```
/komodo-infra
  /stacks
    frontend.toml
    backend.toml
    database.toml
  /deployments
    monitoring.toml
  /procedures
    deploy-all.toml
    update-all.toml
  /actions
    custom-automation.toml
  sync.toml
```

2. Define Resource Sync configuration (sync.toml):
```toml
[[resource_sync]]
name = "komodo-infrastructure"
description = "All infrastructure as code"

[resource_sync.config]
repo = "username/komodo-infra"
git_account = "github-account"
branch = "main"
resource_path = [
  "stacks/*.toml",
  "deployments/*.toml",
  "procedures/*.toml",
  "actions/*.toml"
]
managed = true
files_on_stack = false
git_provider = "github"
```

3. Create individual resource definitions:

**Example: stacks/frontend.toml**
```toml
[[stack]]
name = "frontend"
description = "Frontend React application"

[stack.config]
server = "main-server"
repo = "username/frontend-app"
git_account = "github-account"
branch = "main"
file_paths = ["docker-compose.yml"]

[stack.config.environment]
NODE_ENV = "production"
API_URL = "${API_URL}"
APP_VERSION = "${APP_VERSION}"

[[stack.config.after]]
"database"
```

**Example: procedures/deploy-all.toml**
```toml
[[procedure]]
name = "deploy-all-production"
description = "Deploy all production services"

[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "BatchDeployStackIfChanged"
params = { pattern = "prod-*" }
```

4. Set up workflow:
   - Commit resource definitions to Git
   - Create Resource Sync in Komodo UI
   - Configure webhook for auto-sync
   - Test by making changes in UI
   - Verify changes committed back to Git (bidirectional sync)
   - Test by making changes in Git
   - Verify changes applied in Komodo

**Best Practices:**
- Use managed mode for Komodo to own resource state
- Organize resources by type in subdirectories
- Use `after` arrays for deployment ordering
- Version control all infrastructure changes
- Review changes via Git PR process before merge
- Enable webhook for automatic sync
- Use bidirectional sync for UI changes
- Document resource configurations

### Task 5: Configure Build and Auto-Deploy Workflow

**Context:** Automate building Docker images and deploying to environments on Git push.

**Steps:**
1. Create Build resource configuration:
```toml
[[build]]
name = "my-app-build"
description = "Build Docker image from Git"

[build.config]
repo = "username/my-app"
git_account = "github-account"
branch = "main"
builder = "main-server-builder"
docker_account = "dockerhub-account"

[build.config.build_args]
NODE_VERSION = "20"
BUILD_ENV = "production"

[build.config.image]
name = "username/my-app"
tag = "latest"
```

2. Create Deployment resource configuration:
```toml
[[deployment]]
name = "my-app-deployment"
description = "Deploy my-app container"

[deployment.config]
server = "main-server"
build = "my-app-build"
network = "host"

[deployment.config.environment]
PORT = "3000"
DB_HOST = "${DB_HOST}"
DB_PASSWORD = "${DB_PASSWORD}"

[[deployment.config.volumes]]
host = "/data/app"
container = "/app/data"

[deployment.config.restart]
policy = "unless-stopped"

[deployment.config.auto_update]
enabled = true
```

3. Configure webhooks:
   - Get Build webhook URL from Komodo
   - Add webhook to Git repository
   - Set trigger events: push to main branch
   - Configure webhook secret
   - Test with a push to repository

4. Verify workflow:
   - Push code to Git → Webhook triggers Build
   - Build completes → Image pushed to registry
   - Deployment auto-updates to new image
   - Container restarts with new version

**Best Practices:**
- Use semantic versioning for image tags
- Enable auto-update for development/staging
- Use "Poll for Updates" for production (manual approval)
- Configure build notifications via Alerter
- Use AWS Builder for burst capacity
- Set resource limits on deployments
- Use health checks in containers
- Monitor build success/failure rates

## API Usage Patterns

### Using TypeScript SDK
```typescript
import { KomodoClient } from 'komodo_client';

const client = KomodoClient({
  url: "https://komodo.example.com",
  type: "api-key",
  params: {
    key: "your-api-key",
    secret: "your-api-secret"
  }
});

// Read operations
const stacks = await client.read("ListStacks", {});
const deployment = await client.read("GetDeployment", {
  deployment: "my-app"
});

// Execute operations
await client.execute("DeployStack", { stack: "frontend" });
await client.execute("RunBuild", { build: "my-app-build" });

// Write operations
await client.write("UpdateStack", {
  name: "frontend",
  config: { /* updated configuration */ }
});
```

### Using CLI (`km`)
```bash
# List containers
km ps --down

# Deploy resources
km deploy-stack frontend
km run-build my-app-build
km deploy my-app-deployment

# Run automation
km run action sync-branches
km run procedure deploy-all-production

# Maintenance
km prune-system
km database backup

# Skip confirmations (CI/CD)
km deploy-stack frontend --yes
```

### In Actions (Pre-initialized Client)
```typescript
// 'komodo' client is already available
const stacks = await komodo.read("ListStacks", {});

// Access webhook data
const branch = WEBHOOK_BRANCH;
const payload = WEBHOOK_BODY;

// Access action arguments
const environment = ARGS.environment || "production";
const dryRun = ARGS.dryRun || false;

// Perform operations
for (const stack of stacks) {
  if (stack.name.includes(environment)) {
    await komodo.execute("DeployStack", { stack: stack.name });
  }
}
```

## Configuration Patterns

### Environment Variables
**Core (.env):**
```bash
# Essential
KOMODO_PASSKEY=random_secure_passkey
KOMODO_HOST=https://komodo.example.com
KOMODO_TITLE="Production Komodo"

# Initial setup
KOMODO_INIT_ADMIN_USERNAME=admin
KOMODO_INIT_ADMIN_PASSWORD=secure_password
KOMODO_FIRST_SERVER=http://192.168.1.10:8120

# Automation
KOMODO_RESOURCE_POLL_INTERVAL=3600
KOMODO_WEBHOOK_SECRET=webhook_secret

# OAuth (optional)
KOMODO_GITHUB_OAUTH_ENABLED=true
KOMODO_GITHUB_OAUTH_ID=github_client_id
KOMODO_GITHUB_OAUTH_SECRET=github_client_secret
```

**Periphery (periphery.toml):**
```toml
passkey = "matches_komodo_passkey"
port = 8120

[directories]
repo_dir = "/opt/komodo/repos"
stack_dir = "/opt/komodo/stacks"

[security]
allowed_ips = ["192.168.1.0/24"]
```

### Secrets and Variables
**Core Config (core.toml):**
```toml
[secrets]
DB_PASSWORD = "secret_database_password"
API_KEY = "secret_api_key"
JWT_SECRET = "jwt_signing_secret"

[variables]
APP_VERSION = "1.0.0"
ENVIRONMENT = "production"
API_URL = "https://api.example.com"
```

**Usage in Resources:**
```yaml
# docker-compose.yml
services:
  app:
    environment:
      - DB_PASSWORD=${DB_PASSWORD}
      - API_KEY=${API_KEY}
      - APP_VERSION=${APP_VERSION}
```

## Troubleshooting Guide

### Issue: Stack fails to deploy
**Diagnosis:**
1. Check Stack logs in Komodo UI
2. Verify Server connection and health
3. Check docker-compose.yml syntax
4. Verify environment variables are set
5. Check image availability in registry

**Resolution:**
```bash
# On Periphery server
docker compose -f /path/to/stack/docker-compose.yml config
docker compose -f /path/to/stack/docker-compose.yml up -d
```

### Issue: Build fails
**Diagnosis:**
1. Check Build logs in Komodo
2. Verify Dockerfile exists in repository
3. Check Builder connectivity
4. Verify build arguments
5. Check Docker registry credentials

**Resolution:**
- Test build locally: `docker build -t test .`
- Verify Builder has Docker access
- Check registry authentication
- Review build args and secrets

### Issue: Webhook not triggering
**Diagnosis:**
1. Verify webhook URL is correct
2. Check webhook secret matches
3. Review Git provider webhook delivery logs
4. Check Komodo webhook logs
5. Verify KOMODO_WEBHOOK_SECRET is set

**Resolution:**
- Test webhook manually in Git provider
- Check Komodo logs for webhook receipt
- Verify content type is application/json
- Ensure webhook secret matches
- Check firewall rules

### Issue: Periphery unreachable
**Diagnosis:**
1. Check Periphery service status: `systemctl status komodo-periphery`
2. Verify port 8120 is open
3. Check passkey configuration
4. Verify IP whitelisting
5. Check network connectivity from Core to Periphery

**Resolution:**
```bash
# Restart Periphery
systemctl restart komodo-periphery

# Check logs
journalctl -u komodo-periphery -f

# Test connectivity
curl http://periphery-host:8120/health

# Verify firewall
ufw status
```

### Issue: Resource Sync not applying changes
**Diagnosis:**
1. Check Resource Sync status in UI
2. Verify TOML syntax is valid
3. Check Git repository accessibility
4. Review Resource Sync logs
5. Verify webhook is configured

**Resolution:**
- Validate TOML: Use TOML validator
- Check Git credentials
- Manually trigger sync in UI
- Review error messages in logs
- Verify `managed = true` in config

## Security Best Practices

### Network Security
- Always use reverse proxy for HTTPS (Caddy, Nginx, Traefik)
- Firewall Periphery port 8120: Only allow Core IP
- Use IP whitelisting in Periphery config
- Disable direct internet access to Core/Periphery ports
- Use VPN for remote access (Tailscale, WireGuard, Pangolin)

### Authentication & Authorization
- Rotate API keys regularly
- Use OAuth/OIDC for team access
- Implement User Groups for permission management
- Follow principle of least privilege
- Enable user approval workflow
- Review permissions regularly

### Secrets Management
- Store secrets in Komodo Core config, not in compose files
- Use variable interpolation: `${SECRET_NAME}`
- Consider external secret management (1Password, Vault)
- Use file-based secrets for Docker Compose: `${SECRET}_FILE`
- Never commit secrets to Git
- Rotate secrets periodically

### Infrastructure Security
- Keep Komodo Core and Periphery updated
- Regular security audits of resources
- Monitor audit logs for suspicious activity
- Use read-only permissions where possible
- Enable alerting for security events
- Regular backups of Komodo database

## Performance Optimization

### Deployment Performance
- Use host networking when possible (lower overhead)
- Configure resource limits (CPU, memory) appropriately
- Use monorepo structure for multiple stacks (single clone)
- Local builders for frequent builds
- AWS builders for burst capacity
- Prune unused Docker resources regularly

### Monitoring Performance
- Set appropriate polling intervals (avoid too frequent)
- Use alerter unresolved timeout to prevent spam
- Configure critical thresholds realistically
- Use batch operations for multiple resources
- Leverage procedure stages for parallelization

### Build Performance
- Use Docker layer caching effectively
- Multi-stage builds for smaller images
- Use .dockerignore to exclude unnecessary files
- Consider build argument reuse
- Use local registry for private dependencies

## Integration Examples

### GitHub Actions Integration
```yaml
# .github/workflows/deploy.yml
name: Deploy to Komodo

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install Komodo CLI
        run: |
          cargo install komodo_cli

      - name: Configure Komodo
        run: |
          mkdir -p ~/.config/komodo
          cat > ~/.config/komodo/creds.toml <<EOF
          url = "${{ secrets.KOMODO_URL }}"
          key = "${{ secrets.KOMODO_KEY }}"
          secret = "${{ secrets.KOMODO_SECRET }}"
          EOF

      - name: Deploy
        run: |
          km run-build my-app-build --yes
          km deploy-stack production-stack --yes
```

### Renovate Integration
```json
{
  "extends": ["config:base"],
  "docker": {
    "enabled": true
  },
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "automerge": true,
      "automergeType": "branch"
    }
  ]
}
```

### Ansible Integration
```yaml
# playbook.yml
- name: Deploy Komodo Periphery
  hosts: docker_hosts
  tasks:
    - name: Install Periphery
      shell: |
        curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | python3
      environment:
        PERIPHERY_PASSKEY: "{{ komodo_passkey }}"

    - name: Configure Periphery
      template:
        src: periphery.toml.j2
        dest: /etc/komodo/periphery.toml
```

## Reference Files

### Complete Stack Example
```toml
[[stack]]
name = "production-app"
description = "Production application stack"

[stack.config]
server = "prod-server"
repo = "company/production-app"
git_account = "github-prod"
branch = "main"
file_paths = ["docker-compose.yml", "configs/app.json"]

[stack.config.environment]
NODE_ENV = "production"
APP_VERSION = "${APP_VERSION}"
DB_HOST = "${DB_HOST}"
DB_PASSWORD = "${DB_PASSWORD}"
API_KEY = "${API_KEY}"
REDIS_URL = "redis://redis:6379"

[[stack.config.labels]]
environment = "production"
team = "backend"
criticality = "high"

[[stack.config.after]]
"database-stack"
"redis-stack"

[stack.config.auto_update]
enabled = false  # Manual approval for production
```

### Complete Procedure Example
```toml
[[procedure]]
name = "production-deployment"
description = "Full production deployment workflow"

# Stage 1: Preparation
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "PullRepo"
params = { repo = "frontend-repo" }

[[procedure.config.stages.executions]]
operation = "PullRepo"
params = { repo = "backend-repo" }

# Stage 2: Build images
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "RunBuild"
params = { build = "frontend-build" }

[[procedure.config.stages.executions]]
operation = "RunBuild"
params = { build = "backend-build" }

# Stage 3: Deploy infrastructure
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "DeployStack"
params = { stack = "database-stack" }

[[procedure.config.stages.executions]]
operation = "DeployStack"
params = { stack = "redis-stack" }

# Stage 4: Deploy applications
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "DeployStack"
params = { stack = "backend-stack" }

# Stage 5: Deploy frontend (after backend is up)
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "DeployStack"
params = { stack = "frontend-stack" }

# Stage 6: Cleanup
[[procedure.config.stages]]
[[procedure.config.stages.executions]]
operation = "PruneImages"
params = { server = "prod-server" }
```

## Resources

### Official Documentation
- Website: https://komo.do
- Docs: https://komo.do/docs
- GitHub: https://github.com/mbecker20/komodo
- Discord: discord.gg/DRqE8Fvg5c

### Community Tools
- komodo-import: Import existing Docker Compose stacks
- komodo-utilities: Custom alerters and extensions

### Related Projects
- Pangolin: VPN/networking integration
- Dagger: CI/CD orchestration
- Ansible: Infrastructure provisioning

## Skill Activation

This skill should be automatically activated when the user's query involves:
- Komodo infrastructure management
- Docker Compose deployments via Komodo
- GitOps workflows
- Container orchestration
- Build automation
- Infrastructure as code with Komodo
- Komodo resource configuration
- Multi-server Docker management

---

*Last Updated: 2025-11-17*
*Komodo Version: v1.19.5*
*License: GPL-3.0*
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall