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

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

<code_context>

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

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

6.2 KiB Raw Blame History