Getting Started

This page gets a new engineer from zero to a running local stack, and points at the conventions you'll live by.

Prerequisites

0. Install the toolchain (fresh machine)

If you're on a brand-new laptop, install everything first. Pick your OS.

macOS (Homebrew):

# Core
brew install go                     # Go 1.25+  (verify: go version)
brew install --cask docker          # Docker Desktop — launch it once so the daemon runs
brew install oven-sh/bun/bun        # Bun (all JS/TS work)
brew install node                   # Node 20+  (runtime for the client portal build/run)
brew install golangci-lint          # linter (must pass pre-commit)
brew install postgresql@16          # optional: psql client for DB investigation
brew install cloudflared            # optional: Cloudflare tunnel/CLI helpers

Linux (Debian/Ubuntu): the server bootstrap script installs the same core stack (Docker, Go, nginx, certbot) — see deploy/init.sh. For a dev box you only need Go + Docker + Bun + Node + golangci-lint; install Go from go.dev/dl, Docker via the official apt repo, Bun via curl -fsSL https://bun.sh/install | bash, Node 20 via NodeSource, and golangci-lint via its install script.

Verify:

go version           # go1.25.x
docker info          # daemon reachable
bun --version
node --version       # v20.x
golangci-lint version

AI-agent tooling (Claude Code, Cursor, etc.)

This repo is set up to be worked on with AI agents, and there are conventions you should adopt on day one:

• CLAUDE.md (repo root) — the project brief loaded into every Claude Code session: commands, architecture, coding standards, and the absolute DB safety rule (no ad-hoc writes). Cursor/Copilot users should read it too.
• AGENTS.md — detailed coding standards for AI agents (errcheck patterns, test-design rules, common codebase patterns). CLAUDE.md defers to it.
• .claude/settings.local.json — per-repo Claude Code permission allow-list (which Bash/WebFetch calls run without a prompt). Safe to extend; it's how you cut down permission prompts for common commands like go build, go test, bun run, wrangler d1 migrations apply.
• Cloudflare MCP — the live Cloudflare account can be introspected read-only via the Cloudflare MCP server (this is how the Cloudflare page was built). Add it in your Claude Code MCP settings if you'll manage CF.
• Persistent memory — the previous maintainer accumulated a large body of project-specific knowledge in Claude's memory; it's preserved verbatim in the Memory Appendix. Skim it before making changes.

1. Clone & start the data plane

git clone <repo> octopus && cd octopus
docker compose up -d          # postgres:5432, valkey:6379, rabbitmq:5672 (+15672 UI), otel:4328, mysql:3306

The compose stack uses user/pass octopus/octopus for Postgres and RabbitMQ by default. Data persists under ./.data/.

2. Configure env

The backend auto-loads a .env at the repo root (via godotenv/autoload). There is no central config struct — config is read ad-hoc through utils.FetchEnv(name, default). The important variables:

# Core
PORT=:8081
APP_ENV=local
LOG_LEVEL=info

# Feature flags — turn on the verticals you need
FEATURE_VOUCHERS_ENABLED=true
FEATURE_TOPUPS_ENABLED=true
FEATURE_ESIM_ENABLED=true
FEATURE_PAYOUTS_ENABLED=false
FEATURE_SHOPIFY_ENABLED=false

# Database (postgres default; sqlite also supported via DATABASE=sqlite)
PG_HOST=localhost
PG_PORT=5432
PG_USER=octopus
PG_PASS=octopus
PG_DB=octopus

# Cache & queue
CACHE_TYPE=valkey          # or memory / nil
VALKEY_ADDR=localhost:6379
QUEUE_PROVIDER=rabbitmq     # or memory
QUEUE_CONNECTION=amqp://octopus:octopus@localhost:5672/
QUEUE_EXCHANGE=app.default

# Auth (generate real secrets for anything shared)
JWT_SECRET=<openssl rand -base64 64>
APP_KEY=<openssl rand -base64 32>

# Observability (optional locally)
OTEL_ENABLED=false

See Architecture → Configuration for the full env catalogue.

3. Migrate & seed

go run main.go migrate up        # apply all pending Goose migrations
go run main.go seed all          # reference data + fixtures (idempotent)
# or: go run main.go seed fresh   # reference data only, preserves clients & vendors

4. Run the app

go run main.go server --debug    # HTTP API on :8081, pprof on :6060
go run main.go run-all --debug   # server + workers + all crons together (prod-style)
go run main.go cron inventory-pump pending-order-retry   # run specific crons only

• API: http://localhost:8081 (routes under /api/v1, /auth, /client, /g2a, /webhooks).
• Admin UI (Jet templates): http://localhost:8081/admin.

5. Run a frontend (example: client portal)

cd frontend/client
bun install
bun run dev        # Next.js on :3001 (Turbopack)

Grasshopper (claim worker): cd frontend/grasshopper && bun install && bun run dev (Wrangler dev on :8787). Local secrets go in .dev.vars (see .dev.vars.example).

Day-to-day: adding things

Pre-commit checklist

Every change must pass:

go build ./...
go vet ./...
go fmt ./...
golangci-lint run ./...
go test ./...

Plus: no hardcoded secrets, no PROD URLs in test files, and X-Automation-Request safety verified (automation requests are blocked in prod). See CLAUDE.md / AGENTS.md for the full standards, and the Memory Appendix for house rules like errcheck patterns and test-design conventions.

The verbatim knowledge base

The previous maintainer accumulated a large body of project-specific knowledge — spec-drift notes for vendors, architectural decisions, UI conventions, and more. All of it is preserved in the Memory Appendix. When something surprises you, check there first.