# Phase 9: Tooling & Portable Setup - Context
**Gathered:** 2026-06-14
**Status:** Ready for planning
## Phase Boundary
Create a custom Docker image with essential platform engineering tools and a portable setup script that can provision a fresh macOS machine with all ngn-agent configuration in a single invocation.
**In scope:** Custom Dockerfile in project repo, image build tooling, parameterized setup script covering all config, file creation, volume mounts, skills, and cron jobs
**Out of scope:** Installing Hermes Agent itself (assumes Hermes v0.16+ is installed), cloud-native deployment (macOS-only setup), multi-architecture image builds
## Implementation Decisions
### Custom Docker Image
- **D-01:** Dockerfile lives in this repo at `ngn-agent/docker/Dockerfile` — extends `nikolaik/python-nodejs:python3.11-nodejs20`
- **D-02:** Pin specific tool versions — Dockerfile should specify exact versions for reproducibility
- **D-03:** Tools to include:
- **aws-cli**: v2 (latest stable)
- **terraform**: latest stable
- **helm**: latest stable
- **kubectl**: latest stable matching cluster version
- **datadog CLI** (`pup`): latest stable
- **D-04:** Build script at `ngn-agent/docker/build.sh` — single command to build the image
- **D-05:** Image tag: `ngn-agent:latest` (local only, no registry push)
### Portable Setup Script
- **D-06:** Single script at `ngn-agent/setup-ngn-agent.sh` — recreates all configuration on a fresh machine
- **D-07:** Assumes Hermes v0.16+ is already installed and `hermes` CLI is on PATH
- **D-08:** Interactive prompts for all secrets:
- `JIRA_API_TOKEN` (required for Atlassian integrations)
- `JIRA_EMAIL` (required for Atlassian integrations)
- `TELEGRAM_BOT_TOKEN` (required for gateway)
- `OPENROUTER_API_KEY` (if not already set)
- **D-09:** Configurable parameters (supplied via args or prompts):
- SSH key paths (default: `~/.ssh/id_ed25519razer`, `~/.ssh/id_rsa`)
- SSH config path (default: `~/.ssh/config`)
- SSH known_hosts path (default: `~/.ssh/known_hosts`)
- Repo paths (default: `~/Razer/rai-ops`, `~/Razer/rai-deployment`, `~/Razer/rai-devtools`)
- Timezone (default: `Asia/Singapore`)
- **D-10:** What the setup script creates/updates:
- `~/.hermes/config.yaml` — docker_volumes (SSH + repo mounts), shell_init_files, docker_forward_env, cron config
- `~/.hermes/.env` — secrets and DEFAULT_REPOS
- `~/.hermes/hindsight/config.json` — Hindsight config
- `~/.hermes/scripts/session-init.sh` — mount verification script
- `~/.hermes/scripts/archive-stale-sessions.sh` — archive script
- `~/.hermes/skills/ngn-agent/` — all 5 skill directories
- `~/.hermes/archive/sessions/` — archive directory
- Register 3 cron jobs (ngn-daily-report, ngn-weekly-stale-summary, ngn-weekly-archive)
- Update Docker image reference in config.yaml
### the agent's Discretion
- **Dockerfile tool version selection**: Choose stable versions current at time of implementation
- **Setup script structure**: Interactive prompt flow, output formatting, error handling approach
- **Config file templates**: How to generate config.yaml sections, .env format, etc.
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Project Repo
- `.planning/REQUIREMENTS.md` §TOOL-01, SETUP-01 — Requirement definitions
- `.planning/ROADMAP.md` §Phase 9 — Phase goal and success criteria
### Current Configuration (what the setup script must recreate)
- `~/.hermes/config.yaml` — Full config with docker_volumes, shell_init_files, docker_forward_env, cron, memory.provider, telegram
- `~/.hermes/.env` — All env vars (JIRA_API_TOKEN, JIRA_EMAIL, TELEGRAM_BOT_TOKEN, OPENROUTER_API_KEY, DEFAULT_REPOS, HINDSIGHT_LLM_API_KEY)
- `~/.hermes/hindsight/config.json` — Hindsight local_embedded config with all settings
- `~/.hermes/scripts/session-init.sh` — Mount verification script
- `~/.hermes/scripts/archive-stale-sessions.sh` — Session archive script
- `~/.hermes/skills/ngn-agent/` — 5 skill files (aws-diagnostics, jira, confluence, bitbucket, session)
- `.planning/phases/08-cron-reporting/08-01-SUMMARY.md` — Cron job registrations
- `.planning/phases/08-cron-reporting/08-02-SUMMARY.md` — Weekly cron job details
### Base Image
- `nikolaik/python-nodejs:python3.11-nodejs20` — Current Hermes Docker image
### Existing Skills (templates for setup script)
- `~/.hermes/skills/ngn-agent/aws-diagnostics/SKILL.md`
- `~/.hermes/skills/ngn-agent/jira/SKILL.md`
- `~/.hermes/skills/ngn-agent/confluence/SKILL.md`
- `~/.hermes/skills/ngn-agent/bitbucket/SKILL.md`
- `~/.hermes/skills/ngn-agent/session/SKILL.md`
## Existing Code Insights
### Reusable Assets
- **Hermes config.yaml** — Current state is the source of truth for what setup script must recreate
- **Skill files** — 5 existing SKILL.md files that setup script must copy into place
- **Script files** — session-init.sh and archive-stale-sessions.sh that setup script must copy
- **Hindsight config.json** — Current config that setup script must create
### Integration Points
- `ngn-agent/docker/Dockerfile` — New file (create)
- `ngn-agent/docker/build.sh` — New file (create)
- `ngn-agent/setup-ngn-agent.sh` — New file (create)
- `~/.hermes/config.yaml` — Modified by setup script
- `~/.hermes/.env` — Created by setup script with user-provided secrets
## Specific Ideas
- The setup script should use `hermes config set` where possible instead of raw YAML editing
- Secrets should be prompted interactively with masked input where the terminal supports it
- The setup script should validate prerequisites (Hermes installed, Docker running, SSH keys exist) before making changes
- The Dockerfile should install tools via apt-get and pip where possible, with version pinning via checksums or apt version strings
- After setup, script should offer to restart the Hermes gateway
## Deferred Ideas
- Multi-architecture image builds (arm64 + amd64) — defer until needed
- Cloud-native deployment (Docker Compose, Fly.io, etc.) — out of scope
- CI/CD for image builds — out of scope
---
*Phase: 9-Tooling & Portable Setup*
*Context gathered: 2026-06-14*