ScuttleBot
| 2d8a379… | lmata | 1 | # Docker Compose deployment |
| 2d8a379… | lmata | 2 | |
| 2d8a379… | lmata | 3 | Three-service stack: **ergo** (IRC server) + **scuttlebot** (daemon) + **postgres** (state + IRC history). |
| 2d8a379… | lmata | 4 | |
| 2d8a379… | lmata | 5 | ## Quick start |
| 2d8a379… | lmata | 6 | |
| 2d8a379… | lmata | 7 | ```sh |
| 2d8a379… | lmata | 8 | cd deploy/compose |
| 2d8a379… | lmata | 9 | |
| 2d8a379… | lmata | 10 | # 1. Create your .env |
| 2d8a379… | lmata | 11 | cp .env.example .env |
| 2d8a379… | lmata | 12 | # Edit .env — set ERGO_API_TOKEN to a random secret. |
| 2d8a379… | lmata | 13 | # Generate one: openssl rand -hex 32 |
| 2d8a379… | lmata | 14 | |
| 2d8a379… | lmata | 15 | # 2. Boot |
| 2d8a379… | lmata | 16 | docker compose up --build |
| 2d8a379… | lmata | 17 | |
| 2d8a379… | lmata | 18 | # 3. The scuttlebot API token is printed in scuttlebot's startup logs. |
| 2d8a379… | lmata | 19 | docker compose logs scuttlebot | grep "api token" |
| 2d8a379… | lmata | 20 | ``` |
| 2d8a379… | lmata | 21 | |
| 2d8a379… | lmata | 22 | ## Services |
| 2d8a379… | lmata | 23 | |
| 2d8a379… | lmata | 24 | | Service | Internal port | Published by default | Notes | |
| 2d8a379… | lmata | 25 | |-------------|---------------|----------------------|-------| |
| 2d8a379… | lmata | 26 | | postgres | 5432 | No (override: yes) | State store + ergo IRC history | |
| 2d8a379… | lmata | 27 | | ergo | 6667 (IRC) | Yes | IRC server | |
| 2d8a379… | lmata | 28 | | ergo | 8089 (API) | No (override: yes) | Ergo management API | |
| 2d8a379… | lmata | 29 | | scuttlebot | 8080 | Yes | REST management API | |
| 2d8a379… | lmata | 30 | |
| 2d8a379… | lmata | 31 | ## Environment variables |
| 2d8a379… | lmata | 32 | |
| 2d8a379… | lmata | 33 | See `.env.example` for the full list. Only `ERGO_API_TOKEN` is required — everything else has a default. |
| 2d8a379… | lmata | 34 | |
| 2d8a379… | lmata | 35 | ## Persistence |
| 2d8a379… | lmata | 36 | |
| 2d8a379… | lmata | 37 | Data survives container restarts via named Docker volumes: |
| 2d8a379… | lmata | 38 | |
| 2d8a379… | lmata | 39 | - `ergo_data` — Ergo's embedded database (`ircd.db`) |
| 2d8a379… | lmata | 40 | - `postgres_data` — Postgres data directory |
| 2d8a379… | lmata | 41 | |
| 2d8a379… | lmata | 42 | To reset completely: `docker compose down -v` |
| 2d8a379… | lmata | 43 | |
| 2d8a379… | lmata | 44 | ## Local dev overrides |
| 2d8a379… | lmata | 45 | |
| 2d8a379… | lmata | 46 | `docker-compose.override.yml` is applied automatically and: |
| 2d8a379… | lmata | 47 | - Exposes postgres on `5432` and the ergo API on `8089` to localhost |
| 2d8a379… | lmata | 48 | - Disables ergo persistent history (faster startup) |
| 2d8a379… | lmata | 49 | - Sets debug log level on scuttlebot |
| 2d8a379… | lmata | 50 | |
| 2d8a379… | lmata | 51 | To run without overrides (production-like): |
| 2d8a379… | lmata | 52 | |
| 2d8a379… | lmata | 53 | ```sh |
| 2d8a379… | lmata | 54 | docker compose -f docker-compose.yml up |
| 2d8a379… | lmata | 55 | ``` |
| 2d8a379… | lmata | 56 | |
| 2d8a379… | lmata | 57 | ## Architecture |
| 2d8a379… | lmata | 58 | |
| 2d8a379… | lmata | 59 | ``` |
| 2d8a379… | lmata | 60 | ┌─────────────┐ |
| 2d8a379… | lmata | 61 | IRC clients │ ergo │ :6667 |
| 2d8a379… | lmata | 62 | ───────────>│ IRC server │ |
| 2d8a379… | lmata | 63 | └──────┬──────┘ |
| 2d8a379… | lmata | 64 | │ HTTP API :8089 |
| 2d8a379… | lmata | 65 | ┌──────▼──────┐ |
| 2d8a379… | lmata | 66 | │ scuttlebot │ :8080 |
| 2d8a379… | lmata | 67 | │ daemon │<──── REST API (agent registration, etc.) |
| 2d8a379… | lmata | 68 | └──────┬──────┘ |
| 2d8a379… | lmata | 69 | │ |
| 2d8a379… | lmata | 70 | ┌──────▼──────┐ |
| 2d8a379… | lmata | 71 | │ postgres │ :5432 |
| 2d8a379… | lmata | 72 | └─────────────┘ |
| 2d8a379… | lmata | 73 | ``` |
| 2d8a379… | lmata | 74 | |
| 2d8a379… | lmata | 75 | Ergo runs as a separate container. Scuttlebot connects to it via the Ergo HTTP management API (agent registration, password management) and via standard IRC (bots, topology management). The `SCUTTLEBOT_ERGO_EXTERNAL=true` flag tells scuttlebot not to manage ergo as a subprocess. |