harb/docs/ENVIRONMENT.md

# ENVIRONMENT.md — Local Dev Stack

How to start, stop, and verify the harb development environment.

## Stack Overview

Docker Compose services (in startup order):

| Service | Purpose | Port | Health Check |
|---------|---------|------|-------------|
| **anvil** | Local Ethereum fork (Base Sepolia) | 8545 | JSON-RPC response |
| **postgres** | Ponder database | 5432 | pg_isready |
| **bootstrap** | Deploys contracts to anvil | — | One-shot, exits 0 |
| **ponder** | On-chain indexer + GraphQL API | 42069 | HTTP /ready or GraphQL |
| **landing** | Landing page (Vue 3 + Vite) | 5174 | HTTP response |
| **webapp** | Staking app (Vue 3) | 5173 | HTTP response |
| **txn-bot** | Automated recenter/tx bot | — | Process alive |
| **caddy** | Reverse proxy / TLS | 80/443 | — |
| **otterscan** | Block explorer | 5100 | — |

## Quick Start

```bash
cd /home/debian/harb

# Start everything
docker compose up -d

# Wait for bootstrap (deploys contracts, ~60-90s)
docker compose logs -f bootstrap

# Check all healthy
docker compose ps
```

## Verify Stack Health

```bash
# Anvil (local chain)
curl -s http://localhost:8545 -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq .result

# Ponder (indexer + GraphQL)
curl -s http://localhost:42069/graphql -X POST \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ stats { id } }"}' | jq .

# Landing page
curl -sf http://localhost:5174 | head -5

# Staking app
curl -sf http://localhost:5173 | head -5
```

## Container Network

Services communicate on `harb-network` Docker bridge.
Internal hostnames match service names (e.g., `ponder:42069`).

Landing page container IP (for Playwright testing): check with
```bash
docker inspect landing --format '{{.NetworkSettings.Networks.harb_harb-network.IPAddress}}'
```

## Common URLs (for testing/review)

- **Landing:** `http://172.18.0.6:5174` (container IP) or `http://localhost:5174`
- **Staking app:** `http://localhost:5173/app/`
- **Ponder GraphQL:** `http://localhost:42069/graphql`
- **Anvil RPC:** `http://localhost:8545`

## Resource Notes

- 8GB VPS — running full stack uses ~4-5GB RAM
- npm install inside containers can OOM with all services running
- Landing container takes ~2min to restart (npm install + vite startup)
- 4GB swap is essential for CI + stack concurrency

## Staking App Passwords

For testing login: `lobsterDao`, `test123`, `lobster-x010syqe?412!`
(defined in `web-app/src/views/LoginView.vue`)

## Webapp Environment Variables

| Variable | Default | Set in docker-compose | Purpose |
|---|---|---|---|
| `VITE_ENABLE_LOCAL_SWAP` | `false` (unset) | `true` | Show inline ETH→$KRK swap widget on Get KRK page instead of the Uniswap link. Enable for local dev; leave unset for production builds. |
| `VITE_KRAIKEN_ADDRESS` | from `deployments-local.json` | via `contracts.env` | Override KRK token address. |
| `VITE_STAKE_ADDRESS` | from `deployments-local.json` | via `contracts.env` | Override Stake contract address. |
| `VITE_DEFAULT_CHAIN_ID` | auto-detected (31337 on localhost) | — | Force the default chain. |

## Contract Addresses

After bootstrap, addresses are in `/home/debian/harb/tmp/containers/contracts.env`.
Landing sources this file on startup for `VITE_KRAIKEN_ADDRESS` and `VITE_STAKE_ADDRESS`.

## Playwright Testing

```bash
# Chromium path
/home/debian/.cache/ms-playwright/chromium-1209/chrome-linux64/chrome

# Run against landing (block fonts for speed)
NODE_PATH=$(npm root -g) node test-script.cjs
```

See `tmp/user-test-r4.cjs` for the most recent test script pattern.