harb/docs/technical/development.md

Docker Development Environment

The Docker stack powers scripts/dev.sh using containerized services. Every boot spins up a fresh Base Sepolia fork, redeploys contracts, seeds liquidity, and launches the live-reload services behind Caddy on port 8081.

Service Topology

• anvil – Base Sepolia fork with optional mnemonic from onchain/.secret.local
• bootstrap – one-shot job running DeployLocal.sol, seeding liquidity, priming blocks, and writing shared env files (uses scripts/bootstrap-common.sh)
• postgres – PostgreSQL 16 database for Ponder indexer state
• ponder – npm run dev for the indexer (port 42069)
• webapp – Vite dev server for web-app (port 5173)
• landing – Vite dev server for landing page (port 5174)
• txn-bot – automation loop plus Express status API (port 43069)
• otterscan – block explorer UI (port 5100)
• caddy – reverse proxy at http://localhost:8081, routing /app/ → webapp, /api/graphql → ponder, /api/rpc → anvil, / → landing

All containers mount the repository so code edits hot-reload exactly as the local script. Named volumes keep node_modules caches between restarts.

Prerequisites

Linux

# Install Docker Engine
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Logout and login again for group changes to take effect

Mac

# Install Colima (open-source Docker Desktop alternative)
brew install colima docker docker-compose

# Start Colima VM with recommended resources
colima start --cpu 4 --memory 8 --disk 100

# Verify installation
docker ps

Launching

Recommended: Use the helper script

./scripts/dev.sh start

This will:

1. Build kraiken-lib
2. Start Anvil (Base Sepolia fork)
3. Deploy contracts via bootstrap
4. Start Ponder (indexes events)
5. Start web-app, landing, txn-bot
6. Start Caddy reverse proxy on port 8081

Startup time: ~6 minutes on first run (includes Ponder indexing 300+ blocks)

Manual approach (not recommended):

docker compose up -d

Stopping the stack:

./scripts/dev.sh stop
# or
docker compose down

Quick restarts for development:

• ./scripts/dev.sh restart --light - Fast restart (~10-20s): only webapp + txnbot, preserves Anvil/Ponder state. Use for frontend changes.
• ./scripts/dev.sh restart --full - Full restart (~6 min): redeploys contracts, fresh state. Use for contract changes.

Important: Every full restart redeploys contracts and rewrites services/ponder/.env.local and tmp/containers/txnBot.env.

Access Points (via Caddy on port 8081)

For reviewing code changes in your browser:

• Landing page: http://localhost:8081/ (marketing site)
• Web-app: http://localhost:8081/app/ (staking interface - use this for testing)
• GraphQL Playground: http://localhost:8081/api/graphql
• TxnBot status: http://localhost:8081/api/txn/status

Direct RPC access:

• Anvil RPC: http://localhost:8081/api/rpc (or http://localhost:8545 directly)

Hot reload workflow:

1. Start stack: ./scripts/dev.sh start
2. Open http://localhost:8081/app/ in your browser
3. Edit files in web-app/src/ - changes appear instantly (Vite HMR)
4. Edit files in landing/src/ - changes appear on http://localhost:8081/
5. Edit smart contracts in onchain/src/ - requires ./scripts/dev.sh restart --full

Configuration Knobs

Set environment variables before docker-compose up:

• FORK_URL – Anvil upstream RPC (defaults to https://sepolia.base.org)
• DEPLOYER_PK, DEPLOYER_ADDR – override deployer wallet; otherwise derived from .secret.local or Foundry defaults
• TXNBOT_PRIVATE_KEY, TXNBOT_ADDRESS, TXNBOT_FUND_VALUE – customise bot signer and funding

Edit containers/Caddyfile if you need different routes or ports.

Known Limitations

• State is ephemeral; every restart wipes the fork and redeploys contracts.
• Processes run in dev/watch mode (npm run dev), so staging traffic is not production hardened.
• Secrets live in env files inside the repo mount because no external secret store is wired in.

Troubleshooting

Mac: "Cannot connect to Docker daemon"

# Ensure Colima is running
colima status
colima start

# Verify Docker can connect
docker ps

Permission errors on Linux

# Add your user to the docker group
sudo usermod -aG docker $USER

# Logout and login again, or use:
newgrp docker

Port conflicts

If you see "port already in use" errors:

# Check what's using the port
lsof -i :8081  # or :8545, :5173, etc.

# Stop conflicting services or change ports in docker-compose.yml