harb/docs/docker.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)
- `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
```bash
# 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
```bash
# 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
```bash
./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):
```bash
docker compose up -d
```

**Stopping the stack:**
```bash
./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"
```bash
# Ensure Colima is running
colima status
colima start

# Verify Docker can connect
docker ps
```

### Permission errors on Linux
```bash
# 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:
```bash
# Check what's using the port
lsof -i :8081  # or :8545, :5173, etc.

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