hermes-recovery/references/docker-management-research.md

# Docker Management — Multi-Host Tool Research

**Date:** 2026-07-09
**Context:** IT Pro Partner runs Docker Compose stacks across multiple servers (Core/netcup, ai.itpropartner.com, docker, unms, etc.). We need a single tool to manage all containers across hosts. Mixed environment of Docker Compose stacks (no Swarm/Kubernetes).

---

## Evaluation Criteria (Priority Order)

1. **Recovery manual completeness** — can Germaine use it without Sho'Nuff?
2. **Multi-host support** — can it see/manage containers on different servers?
3. **CLI/API access** — can I script against it from Hermes?
4. **Self-hosted** — runs on our infrastructure, not SaaS
5. **Free/open source** — no subscription fees for personal use
6. **Web GUI** — nice bonus, not required
7. **Webhook support** — can trigger actions from external events

---

## Tool Comparison Table

| Feature | Portainer | Arcane | Komodo | Dockge | Dockhand | Lazydocker |
|---|---|---|---|---|---|---|
| **Self-hosted** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ❌ (local TUI) |
| **Free tier** | 3 nodes BE free | ✅ 100% FOSS | ✅ 100% FOSS | ✅ 100% FOSS | ✅ Homelab free | ✅ FOSS |
| **Multi-host** | ✅ Agent-based | ✅ Agent-based | ✅ Agent-based | ✅ Agents (v1.4+) | ✅ Agent/TLS | ❌ Single host |
| **REST API** | ✅ Full API | ✅ OpenAPI 3.1 | ✅ REST + WebSocket | ❌ No API | ⏳ Roadmap (distant) | ❌ |
| **Web GUI (1-5)** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ❌ (TUI) |
| **Setup complexity** | Easy | Easy | Medium | Easy | Easy | Very Easy |
| **License** | Proprietary (BE) / MIT (CE) | BSD-3-Clause | GPL-3.0 | MIT | BSL 1.1 → Apache 2.0 (2029) | MIT |
| **Stars** | ~30k | 6.3k | ~3k | 23.7k | 5.1k | 38.7k |
| **Webhooks** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
| **Compose focus** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Compose-only | ✅ Yes | ❌ Container focus |
| **Swarm support** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ❌ Not mentioned | ❌ No |
| **K8s support** | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |

---

## 1. Portainer

**Website:** https://www.portainer.io/
**Docs:** https://docs.portainer.io/
**GitHub:** https://github.com/portainer/portainer

### Overview
Industry-standard Docker management UI. Mature, battle-tested, vast ecosystem. Used by teams of all sizes.

### Pricing
- **Business Edition (BE) — 3 nodes free forever** (full features, no time limit, requires annual license key renewal but $0)
- **Home & Student** — $155/yr for up to 15 nodes (non-commercial only)
- **Business Starter** — $105/mo for 5 nodes (commercial)
- **Business Scale** — $209/mo for 5 nodes
- **Community Edition (CE)** — Free forever but missing RBAC, GitOps, templates, and other BE features

### Multi-host Support
✅ **Yes** — via **Portainer Agent** (lightweight Go daemon on each remote host). Agent connects to Portainer Server. Also supports Docker API over TCP/TLS directly.

### REST API
✅ **Excellent** — comprehensive REST API with Swagger/OpenAPI docs. All UI actions available via API. Official Go client library.

### Setup Complexity: **Easy**
```bash
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
```
One command per remote host, add environment in Portainer UI.

### Recovery Documentation: **Excellent**
- Extensive official docs at https://docs.portainer.io/
- Backup/restore guides: https://docs.portainer.io/advanced/backup
- Large community, thousands of tutorials
- **Germaine-friendly:** Yes — the UI is intuitive, and the docs are thorough

### Pros
- Most mature, most documented
- Free 3-node BE tier covers our needs
- Comprehensive REST API for Hermes scripting
- Agent auto-updates, mTLS support
- Webhooks for GitOps/auto-deploy

### Cons
- Beyond 3 nodes requires payment
- Can feel heavy/bloated for simple Compose management
- CE version lacks features (use BE free tier instead)
- Proprietary license (BE requires license key renewal)

---

## 2. Arcane ⭐ (Strong Contender)

**Website:** https://getarcane.app/
**Docs:** https://getarcane.app/docs/setup/installation
**GitHub:** https://github.com/getarcaneapp/arcane
**Live Demo:** https://demo.getarcane.app/

### Overview
Modern Docker management UI built with SvelteKit (frontend) + Go (backend). BSD-3-Clause licensed. Clean, fast, well-designed. Gaining traction rapidly (6.3k stars, 70 contributors).

### Pricing
- **100% free and open source** — BSD-3-Clause license
- No paid tiers, no feature gating
- Mobile app (iOS TestFlight beta) — also free

### Multi-host Support
✅ **Yes** — via **Arcane Agent** on remote hosts. Two connection modes:
- **Direct** — Manager connects to Agent on TCP 3553 (requires inbound port)
- **Edge** — Agent dials out to Manager (for NAT/firewall, no inbound port needed)
- Transport modes: gRPC tunnel or periodic polling (poll mode for idle environments)

### REST API
✅ **Excellent** — "Fully Documented API" built with Huma on Gin, featuring auto-generated OpenAPI 3.1 documentation. Go client library available.

### Setup Complexity: **Easy**
```bash
# Manager (one line)
docker run -d --name arcane -p 3552:3552 -v arcane_data:/data ghcr.io/getarcaneapp/manager:latest

# Agent on 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
```

### Recovery Documentation: **Good**
- Documentation website at getarcane.app
- Active Discord community
- Growing collection of guides and tutorials
- **Germaine-friendly:** Yes — modern, intuitive UI, good docs

### Key Features
- Container, image, volume, network management
- Docker Compose stack management
- Docker Swarm support
- Image vulnerability scanning (built-in)
- Image building from Dockerfiles
- Resource monitoring (CPU, memory, network)
- RBAC and OIDC/SSO
- GitOps lifecycle hooks
- iOS mobile app
- Webhook triggers

### Pros
- 100% free, no paid tiers ever (BSD-3-Clause)
- Modern, fast, beautiful UI (SvelteKit)
- Excellent REST API with OpenAPI 3.1
- Edge mode for NAT/firewall'd hosts
- Active development (3k+ commits, frequent releases)
- Growing community

### Cons
- Newer project (less battle-tested than Portainer)
- Smaller community (but growing fast)
- No Kubernetes support (not needed for our use case)
- No LDAP/AD (OIDC/SSO available)

---

## 3. Komodo ⭐ (Strong Contender)

**Website:** https://komo.do/
**Docs:** https://komo.do/docs/intro
**GitHub:** https://github.com/moghtech/komodo
**Blog Guide:** https://blog.saltdata.ro/managing-docker-komodo

### Overview
API-first build and deployment system written in Rust (backend) + TypeScript (frontend). GPL-3.0 licensed. Core + Periphery agent architecture. Includes CI/CD pipeline capabilities alongside Docker management.

### Pricing
- **100% free and open source** — GPL-3.0
- No paid tiers, no feature gating
- Unlimited servers — "There is no limit to the number of servers you can connect, and there never will be."

### Multi-host Support
✅ **Yes** — via **Periphery** agent on each remote host. Periphery communicates with Core over a bi-directional WebSocket connection. Can run as systemd service, Docker container, or standalone binary.

### REST API
✅ **Excellent** — REST + WebSocket API with multiple client libraries:
- Komodo CLI (built-in)
- Rust crate (`komodo_client`)
- NPM package (`komodo_client`)
- curl examples in docs

### Setup Complexity: **Medium**
- Core requires MongoDB (or FerretDB/Postgres)
- Docker Compose file with MongoDB + Core
- Periphery agent install via Python script or Docker
- More moving parts than Portainer/Arcane

### Recovery Documentation: **Good**
- Well-organized docs at komo.do
- Built-in backup/restore CLI
- **Germaine-friendly:** Mostly — UI is clean, but setup is more involved

### Key Features
- Docker container and Compose stack management
- Docker Swarm management
- Image building from Dockerfiles (supports AWS EC2 spot instances for build capacity)
- Git repository management on remote servers
- Resource Syncs (GitOps) — auto-deploy on git push
- Procedures — multi-step automation workflows with scheduling
- Server resource monitoring (CPU, RAM, disk)
- RBAC with granular permissions
- OAuth/OIDC authentication
- Full audit trail of every change
- Webhook triggers

### Pros
- Feature-rich — more than just Docker management (builds, CI/CD, automation)
- Excellent API with first-class client libraries (ideal for Hermes scripting)
- Truly unlimited servers
- GPL-3.0 open source
- Active development
- Backup/restore built-in

### Cons
- Heavier setup (needs MongoDB or FerretDB/Postgres)
- More complex than needed if we only need Docker management (CI/CD features may go unused)
- Smaller community than Portainer
- Rust backend — harder to extend/modify than Go

---

## 4. Dockge

**Website:** https://github.com/louislam/dockge
**README:** https://github.com/louislam/dockge/blob/master/README.md

### Overview
Focused Docker Compose stack manager by the creator of Uptime Kuma. MIT licensed. Laser-focused on compose.yaml management rather than general Docker management. Very popular (23.7k stars).

### Pricing
- **100% free and open source** — MIT license

### Multi-host Support
✅ **Yes** — since v1.4.0, supports multiple agents. Can manage stacks from different Docker hosts in one interface.

### REST API
❌ **No documented REST API** — UI-focused tool. No API for external scripting.

### Setup Complexity: **Easy**
```yaml
services:
  dockge:
    image: louislam/dockge:latest
    ports:
      - 5001:5001
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - /opt/stacks:/opt/stacks
    environment:
      - DOCKGE_STACKS_DIR=/opt/stacks
```

### Recovery Documentation: **Minimal**
- README only, no dedicated docs site
- Basic FAQ in README
- **Germaine-friendly:** Partially — UI is simple but recovery docs are thin

### Key Features
- Create/Edit/Start/Stop/Restart compose.yaml stacks
- Interactive compose.yaml editor
- Interactive web terminal for containers
- Multi-agent support (v1.4+)
- Image update button
- Stack folder scanning

### Pros
- Very simple, focused tool (does one thing well)
- Beautiful, reactive UI
- Lightweight and fast
- Large community (23.7k stars)

### Cons
- **Compose-only** — cannot manage individual containers, networks, volumes outside compose
- **No REST API** — cannot be scripted from Hermes
- No webhook support
- No RBAC/authentication (single-user only)
- No monitoring or alerting
- README-only documentation
- "Can I manage existing stacks?" — requires manual file moves

---

## 5. Dockhand

**Website:** https://dockhand.pro/
**Manual:** https://dockhand.pro/manual/
**GitHub:** https://github.com/Finsys/dockhand

### Overview
Modern Docker management platform with polished Svelte UI. BSL 1.1 licensed (converts to Apache 2.0 in 2029). The code IS source-available but not truly open-source in the free-software sense. 5.1k stars.

### Pricing
- **Free tier** — all features for homelab use (no RBAC, no LDAP, no commercial use)
- **SMB** — $499/host/year
- **Enterprise** — $1,499/host/year

### Multi-host Support
✅ **Yes** — three methods:
1. **Local Docker socket** (/var/run/docker.sock)
2. **Remote TCP connections** with TLS
3. **Hawser agent** — lightweight agent for NAT/firewall traversal (similar to Portainer Edge / Arcane Edge)

### REST API
⚠️ **On roadmap ("distant future")** — No working API today. API keys listed as "distant future" on the roadmap. OpenAPI/Swagger also "distant future."

### Setup Complexity: **Easy**
```bash
docker run -d --name dockhand -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest
```

### Recovery Documentation: **Good**
- Full user manual at dockhand.pro/manual
- Well-organized documentation
- **Germaine-friendly:** Yes — polished UI, good manual

### Key Features
- Container operations (start/stop/restart/create)
- Visual Compose editor
- Git repository deployment with webhook auto-sync
- Vulnerability scanning (Grype/Trivy) with safe-pull protection
- Live CPU/memory metrics
- Real-time log streaming
- OIDC/SSO (free)
- MFA (TOTP)
- Hawser agent for NAT traversal
- RBAC and LDAP/AD (Enterprise only)
- Multi-environment switching

### Pros
- Most polished modern UI (5/5)
- 30-second deployment
- Free for homelab use
- Hawser agent handles NAT/firewall well
- Good documentation

### Cons
- **No REST API** — API/API keys are "distant future" on roadmap. Cannot be scripted from Hermes
- BSL 1.1 license — not truly open source (converts to Apache 2.0 in 2029)
- Paid beyond homelab ($499/host/yr for commercial use)
- RBAC and LDAP/AD only in Enterprise tier ($1,499/host/yr)
- Smaller community (5.1k stars)
- Relatively new project (165 commits)

---

## 6. Lazydocker

**Website:** https://lazydocker.com/
**GitHub:** https://github.com/jesseduffield/lazydocker

### Overview
Terminal TUI (Text User Interface) for Docker. MIT licensed. Extremely popular (38.7k stars). Written in Go by the same author as Lazygit. Runs as a local process on a single host.

### Pricing
- **100% free and open source** — MIT license

### Multi-host Support
❌ **No** — runs locally on each host. Cannot manage remote Docker hosts from one interface. Each host needs its own Lazydocker instance (or SSH into each host).

### REST API
❌ **No** — it's a terminal application, not a server.

### Setup Complexity: **Very Easy**
```bash
# Install
brew install lazydocker  # macOS
# Or Docker one-liner
docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock \
  lazyteam/lazydocker
```

### Recovery Documentation: **Minimal**
- README with basic usage
- Keyboard shortcuts reference
- **Germaine-friendly:** Terminal-only — requires comfort with CLI/TUI

### Pros
- Very lightweight and fast
- Great for quick SSH-and-check sessions
- Keyboard-navigable, efficient for power users
- No server infrastructure needed

### Cons
- **Single host only** — cannot manage our multi-server setup
- **No API** — cannot be scripted from Hermes
- **No web GUI** — terminal only (not Germaine-friendly)
- No persistent state or history
- No user management or RBAC

---

## Recommendation: 🦎 Komodo ⭐

### Best Fit for IT Pro Partner

Given our criteria and environment:

| Criterion | Winner | Rationale |
|---|---|---|
| Recovery completeness | **Portainer / Komodo** | Both have excellent docs. Komodo has built-in backup CLI. |
| Multi-host support | **All (except Lazydocker)** | All support agents. Pick based on other criteria. |
| CLI/API access | **Komodo** | REST + WebSocket + 3 client libraries (CLI, Rust, npm) + curl examples. Best API story. |
| Self-hosted | **All (except Lazydocker)** | All run on our infra. |
| Free/open source | **Arcane / Komodo** | Both are 100% free with permissive licenses. |
| Web GUI | **Dockhand / Portainer** | Both have polished UIs. Portainer is more mature. |
| Webhooks | **Komodo / Portainer / Arcane** | All three support webhooks. |

### Top 3 Contenders (Ranked)

#### 1st: **Komodo** 🏆
- **Why:** Best API story (REST + WS + multiple client libs) makes it ideal for Hermes scripting. Core + Periphery architecture handles our mixed environment. GPL-3.0, truly free. Built-in backup/restore. Webhook triggers for GitOps. Unlimited servers. Server monitoring included.
- **Trade-off:** Heavier setup (needs MongoDB). More features than we need if we only want Docker management.

#### 2nd: **Arcane** 🥈
- **Why:** 100% free BSD-3-Clause. Beautiful modern UI. Great multi-host support (Direct + Edge modes). Solid OpenAPI 3.1 REST API. Lightweight Go backend. Built-in vulnerability scanning. iOS mobile app.
- **Trade-off:** Newer project with smaller community. Less documentation than Portainer.

#### 3rd: **Portainer** 🥉
- **Why:** Most mature, best documented, largest community. Free 3-node BE tier covers our needs. Comprehensive REST API. Agent is rock-solid.
- **Trade-off:** Beyond 3 nodes costs money. Covers our current needs but doesn't scale free. Proprietary license.

### Why not the others?
- **Dockge:** No API, no webhooks, compose-only. Good for one-off single-user compose management but not for our multi-host, scriptable needs.
- **Dockhand:** No API (roadmap item, "distant future"). BSL license. Paid for commercial use. Great UI but cannot be scripted by Hermes.
- **Lazydocker:** Single host only. Terminal-only. Good for quick checks but not a management platform.

### Implementation Suggestion
Start with **Komodo** for the API-first multi-host management. If the MongoDB dependency is a concern, **Arcane** is a strong alternative that's lighter to deploy.

### Quick Deploy Comparison

**Komodo** (on management server):
```yaml
# docker-compose.yml for Komodo Core
services:
  mongo:
    image: mongo
    restart: unless-stopped
    volumes:
      - ./data/mongo-data:/data/db
  core:
    image: ghcr.io/moghtech/komodo-core:2
    restart: unless-stopped
    ports:
      - 9120:9120
    depends_on:
      - mongo
    volumes:
      - ./backups:/backups
      - ./keys:/config/keys
```

**Komodo Periphery** (on each managed host):
```bash
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://core.itpropartner.com" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."
```

---

## Links Summary

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