Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,170 @@
+# Komodo Deployment — Reference
+
+**Installed:** 2026-07-09 on Core (netcup RS 2000)
+**Version:** Komodo v2.2.0
+**Purpose:** Multi-host Docker management across ITPP servers (Core, ai, docker, unms, etc.)
+**Architecture:** Core (web UI + API server, port 9120) + MongoDB → Periphery agents on each managed host
+
+## Directory Structure
+
+```
+/root/docker/komodo/
+├── docker-compose.yml      # Core + MongoDB
+├── data/
+│   ├── mongo-data/         # MongoDB persistent storage
+│   └── mongo-config/       # MongoDB config
+├── backups/                # Database backups
+└── keys/
+    ├── core.key            # Core private key (auto-generated)
+    └── core.pub            # Core public key (auto-generated)
+```
+
+## Docker Compose (Core)
+
+```yaml
+services:
+  mongo:
+    image: mongo
+    restart: unless-stopped
+    command: --quiet --wiredTigerCacheSizeGB 0.25
+    volumes:
+      - ./data/mongo-data:/data/db
+      - ./data/mongo-config:/data/configdb
+    networks:
+      - komodo-net
+    deploy:
+      resources:
+        limits:
+          memory: 1G
+
+  core:
+    image: ghcr.io/moghtech/komodo-core:2
+    init: true
+    restart: unless-stopped
+    ports:
+      - 9120:9120
+    depends_on:
+      - mongo
+    volumes:
+      - ./backups:/backups
+      - ./keys:/config/keys
+    environment:
+      # Database
+      - KOMODO_DATABASE_ADDRESS=mongo:27017
+      # Server
+      - KOMODO_PORT=9120
+      - KOMODO_HOST=https://komodo.itpropartner.com
+      - KOMODO_TITLE=Komodo
+      # Auth
+      - KOMODO_LOCAL_AUTH=true
+      - KOMODO_INIT_ADMIN_USERNAME=admin
+      - KOMODO_INIT_ADMIN_PASSWORD=changeme
+      # First server (this host)
+      - KOMODO_FIRST_SERVER_NAME=core
+      # Periphery auth
+      - KOMODO_PERIPHERY_PUBLIC_KEY=file:/config/keys/periphery.pub
+      # Secrets
+      - KOMODO_WEBHOOK_SECRET=komodo-webhook-secret
+      - KOMODO_JWT_SECRET=komodo-jwt-secret-change-me
+      - KOMODO_JWT_TTL=1-day
+      # Monitoring
+      - KOMODO_MONITORING_INTERVAL=15-sec
+      - KOMODO_RESOURCE_POLL_INTERVAL=1-hr
+      # UI
+      - KOMODO_DISABLE_CONFIRM_DIALOG=false
+      - KOMODO_TRANSPARENT_MODE=false
+    networks:
+      - komodo-net
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+
+networks:
+  komodo-net:
+    driver: bridge
+```
+
+## Critical Env Variable Pitfalls (V2)
+
+- **Do NOT use `MONGO_CONNECTION_STRING`** — Komodo v2 uses `KOMODO_DATABASE_ADDRESS=mongo:27017`
+- **Do NOT use `KOMODO_SERVER_PORT`** — use `KOMODO_PORT=9120`
+- **Do NOT use `KOMODO_SERVER_HOST`** — use `KOMODO_BIND_IP=[::]` (default)
+- **`KOMODO_PERIPHERY_PUBLIC_KEY`** must be set with `file:/config/keys/periphery.pub` for auto-generation
+- **`init: true`** is essential on the core container (handles PID 1 zombie reaping properly)
+- **`KOMODO_HOST` must be set** to the URL users will access (used for OAuth redirects, webhook suggestions)
+
+## Startup Log Verification
+
+Successful startup shows:
+```
+Server starting on http://[::]:9120
+Creating init admin user...
+Successfully created init admin user.
+Creating initial system resources...
+```
+
+The admin user is created on first launch only. Core v2.2.0 auto-creates starting resources: "Backup Core Database" procedure and "Global Auto Update" procedure.
+
+## Admin Login (API)
+
+```bash
+# Get JWT token
+curl -s -X POST http://127.0.0.1:9120/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"type":"Local","username":"admin","password":"changeme"}'
+```
+
+Note: the login body requires `"type":"Local"` — missing this field returns: _"Failed to deserialize the JSON body into the target type: missing field `type`"_
+
+## Onboarding Key
+
+The onboarding key is available in the Komodo web UI after login:
+1. Go to the **Servers** page
+2. Click **Add Server / Onboard**
+3. Copy the onboarding key (starts with `O-`)
+
+Or retrieve via the API with a valid JWT:
+```bash
+curl -s http://127.0.0.1:9120/api/core -H "Authorization: Bearer <token>"
+# Extract onboarding_key from response
+```
+
+## Periphery Installation (on each managed host)
+
+```bash
+# Via systemd script (recommended for production)
+curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
+  | python3 - \
+  --core-address="https://komodo.itpropartner.com" \
+  --connect-as="$(hostname)" \
+  --onboarding-key="O-..."
+```
+
+The Periphery agent communicates with Core via WebSocket. It listens on port 8120 by default. The agent runs as a systemd service when installed via the Python script.
+
+## Docker Periphery (alternative, for containers)
+
+```yaml
+services:
+  periphery:
+    image: ghcr.io/moghtech/komodo-periphery:2
+    init: true
+    restart: unless-stopped
+    depends_on:
+      - core
+    env_file: ./compose.env
+    volumes:
+      - keys:/config/keys
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /proc:/proc
+      - ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
+```
+
+## Public Key Authentication
+
+Core uses Noise protocol key pairs for Periphery authentication.
+
+- Core keys auto-generated at: `/config/keys/core.key` and `/config/keys/core.pub`
+- Periphery public key expected at: `/config/keys/periphery.pub` (auto-generated if `KOMODO_PERIPHERY_PUBLIC_KEY` is set and file doesn't exist)
+- Example public key: `-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VuAyEAo+xXlRx+KcxbFkscAx3JcmGKudDwoID3AkGnzjFb1AE=\n-----END PUBLIC KEY-----`