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,145 @@
+# Docker Multi-Host Management Tools — Comparison
+
+**Researched:** 2026-07-09
+**Context:** IT Pro Partner multi-server Docker Compose environment (Core, ai.itpropartner.com, docker, unms, etc.). Need single-pane visibility across hosts, REST API for Hermes scripting, and self-hosted.
+
+## Top 3 Recommendation
+
+### 🏆 1st: **Komodo** — API-first multi-host Docker management
+- **Architecture:** Core (web UI + API) + Periphery (agent on each host)
+- **Why:** Best API story — REST + WebSocket + CLI + Rust/npm client libraries. Perfect for Hermes scripting. GPL-3.0, truly free, unlimited servers. Built-in backup/restore, webhooks, GitOps.
+- **Trade-off:** Needs MongoDB (or FerretDB/Postgres). Heavier setup than alternatives.
+- **Setup:** Docker Compose (Core + Mongo) + Python install script for Periphery agents
+- **Docs:** https://komo.do/docs/intro
+- **GitHub:** https://github.com/moghtech/komodo
+
+### 🥈 2nd: **Arcane** — Modern, BSD-3-Clause, no-MongoDB option
+- **Architecture:** Manager (Go backend + SvelteKit UI) + Agent (Direct or Edge mode)
+- **Why:** 100% free BSD-3-Clause. Beautiful UI. OpenAPI 3.1 REST API. Edge mode handles NAT/firewall'd hosts (agents dial out). Built-in vulnerability scanning. iOS mobile app.
+- **Trade-off:** Newer project (6.3k stars), smaller community than Portainer.
+- **Setup:** Single Docker container for Manager, one per Agent
+- **Docs:** https://getarcane.app/docs/setup/installation
+- **GitHub:** https://github.com/getarcaneapp/arcane
+
+### 🥉 3rd: **Portainer** — Most mature, best documented
+- **Architecture:** Portainer Server + lightweight Go Agent on each host
+- **Why:** Industry standard. Extensive docs. Free BE tier covers 3 nodes with full features. Comprehensive REST API. Agent auto-updates, mTLS.
+- **Trade-off:** Beyond 3 nodes costs money. Heavier/fuller-featured than needed for Compose-only.
+- **Setup:** `docker run` agent command on each host, add via UI
+- **Docs:** https://docs.portainer.io/
+- **GitHub:** https://github.com/portainer/portainer
+
+## All Evaluated Tools
+
+| Tool | Multi-Host | REST API | Free | Web GUI | License | Stars | Setup |
+|---|---|---|---|---|---|---|---|
+| **Portainer** | ✅ Agent | ✅ Full API | 3 nodes free | ⭐⭐⭐⭐⭐ | Proprietary/MIT | ~30k | Easy |
+| **Arcane** | ✅ Agent (Direct+Edge) | ✅ OpenAPI 3.1 | ✅ 100% FOSS | ⭐⭐⭐⭐ | BSD-3-Clause | 6.3k | Easy |
+| **Komodo** 🏆 | ✅ Periphery Agent | ✅ REST + WS + 3 libs | ✅ 100% FOSS | ⭐⭐⭐⭐ | GPL-3.0 | ~3k | Medium |
+| **Dockge** | ✅ Agents (v1.4+) | ❌ No API | ✅ 100% FOSS | ⭐⭐⭐⭐ | MIT | 23.7k | Easy |
+| **Dockhand** | ✅ Agent/TLS/Hawser | ⏳ Roadmap (distant) | ✅ Homelab free | ⭐⭐⭐⭐⭐ | BSL 1.1 | 5.1k | Easy |
+| **Lazydocker** | ❌ Single host | ❌ No API | ✅ 100% FOSS | ❌ TUI only | MIT | 38.7k | Very Easy |
+
+## Why the Others Don't Fit
+
+- **Dockge:** No API, no webhooks, compose-only. Great for single-user compose management but can't be scripted by Hermes.
+- **Dockhand:** No API (roadmap item, "distant future"). BSL license (not truly open source). Paid for commercial use. Beautiful UI but unusable for automation.
+- **Lazydocker:** Single host only. Terminal-only. Good for quick SSH checks, not a management platform.
+
+## Quick Deploy Commands
+
+### Komodo (Correct v2 Env Vars — See references/komodo-deployment.md)
+
+**CRITICAL:** Komodo v2 uses `KOMODO_DATABASE_ADDRESS` (not `MONGO_CONNECTION_STRING`), `KOMODO_PORT` (not `KOMODO_SERVER_PORT`). Using wrong env vars causes startup failure with _"Failed to initialize database"_ errors.
+
+```yaml
+# Core (management server) — full reference in references/komodo-deployment.md
+services:
+  mongo:
+    image: mongo
+    restart: unless-stopped
+    command: --quiet --wiredTigerCacheSizeGB 0.25
+    volumes:
+      - ./data/mongo-data:/data/db
+  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:
+      - KOMODO_DATABASE_ADDRESS=mongo:27017
+      - KOMODO_PORT=9120
+      - KOMODO_HOST=https://komodo.itpropartner.com
+      - KOMODO_TITLE=Komodo
+      - KOMODO_LOCAL_AUTH=true
+      - KOMODO_INIT_ADMIN_USERNAME=admin
+      - KOMODO_INIT_ADMIN_PASSWORD=changeme
+      - KOMODO_FIRST_SERVER_NAME=core
+      - KOMODO_PERIPHERY_PUBLIC_KEY=file:/config/keys/periphery.pub
+      - KOMODO_DISABLE_CONFIRM_DIALOG=false
+      - KOMODO_DISABLE_INIT_RESOURCES=false
+      - KOMODO_JWT_SECRET=change-me
+      - KOMODO_JWT_TTL=1-day
+      - KOMODO_MONITORING_INTERVAL=15-sec
+      - KOMODO_RESOURCE_POLL_INTERVAL=1-hr
+```
+
+```bash
+# Periphery (each managed host)
+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-..."
+```
+
+### Arcane
+```bash
+# Manager
+docker run -d --name arcane -p 3552:3552 \
+  -v arcane_data:/data \
+  ghcr.io/getarcaneapp/manager:latest
+
+# Agent (each remote host)
+docker run -d --name arcane-agent -p 3553:3553 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -e AGENT_MODE=true \
+  -e AGENT_TOKEN=<token> \
+  -e MANAGER_API_URL=http://manager:3552 \
+  ghcr.io/getarcaneapp/agent:latest
+```
+
+### Portainer
+```bash
+# Agent on each remote host
+docker run -d -p 9001:9001 --name portainer_agent --restart=always \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
+  portainer/agent:latest
+```
+
+## Key Links
+| Tool | Website | Docs | GitHub |
+|---|---|---|---|
+| Portainer | https://www.portainer.io/ | https://docs.portainer.io/ | https://github.com/portainer/portainer |
+| Arcane | https://getarcane.app/ | https://getarcane.app/docs/setup/installation | https://github.com/getarcaneapp/arcane |
+| Komodo | https://komo.do/ | https://komo.do/docs/intro | https://github.com/moghtech/komodo |
+| Dockge | https://github.com/louislam/dockge | README only | https://github.com/louislam/dockge |
+| Dockhand | https://dockhand.pro/ | https://dockhand.pro/manual/ | https://github.com/Finsys/dockhand |
+| Lazydocker | https://lazydocker.com/ | README only | https://github.com/jesseduffield/lazydocker |
+
+## Multi-Host Agent Architecture Patterns
+
+All multi-host tools use the same pattern: a central management server + lightweight agents on each Docker host.
+
+| Pattern | Used By | How It Works |
+|---|---|---|
+| **Agent polls out** | Arcane Edge, Dockhand Hawser | Agent behind NAT dials out to manager. No inbound port needed. |
+| **Agent listens** | Portainer Agent, Arcane Direct | Manager connects to agent on a TCP port. Requires inbound access. |
+| **Systemd agent** | Komodo Periphery | Agent runs as systemd service (or Docker). Bi-directional WebSocket to Core. |