58c3e62f3d
- Root AGENTS.md: 350+ lines → 68 lines (map, not encyclopedia) - New docs/dev-environment.md (67 lines): Docker, dev.sh, ports, pitfalls - New docs/ci-pipeline.md (73 lines): Woodpecker setup, monitoring, debugging - New docs/testing.md (41 lines): Foundry, E2E, version validation - New docs/codeberg-api.md (32 lines): .netrc auth, API usage - Updated stale model refs in .claude-code-supervisor.yml files - Sub-component AGENTS.md files unchanged - Context docs (PRODUCT-TRUTH, ARCHITECTURE, UX-DECISIONS) unchanged
67 lines
3.5 KiB
Markdown
67 lines
3.5 KiB
Markdown
# Dev Environment
|
|
|
|
## Prerequisites
|
|
Docker Engine (Linux) or Colima (Mac). See `docs/docker.md` for installation.
|
|
|
|
## Quick Start
|
|
```bash
|
|
nohup ./scripts/dev.sh start & # start (takes ~3-6 min first time)
|
|
tail -f nohup.out # watch progress
|
|
./scripts/dev.sh health # verify all services healthy
|
|
./scripts/dev.sh stop # stop and clean up
|
|
```
|
|
Do not launch services individually — `dev.sh` enforces phased startup with health gates.
|
|
|
|
## Restart Modes
|
|
- `./scripts/dev.sh restart --light` — Fast (~10-20s): only webapp + txnbot, preserves Anvil/Ponder state. Use for frontend changes.
|
|
- `./scripts/dev.sh restart --full` — Full (~3-6min): redeploys contracts, fresh state. Use for contract changes.
|
|
|
|
## Environments
|
|
Supported: `BASE_SEPOLIA_LOCAL_FORK` (default Anvil fork), `BASE_SEPOLIA`, and `BASE`. Match contract addresses and RPCs accordingly.
|
|
|
|
## Ports
|
|
The stack uses these ports:
|
|
| Port | Service |
|
|
|-------|------------|
|
|
| 8545 | Anvil |
|
|
| 5173 | webapp |
|
|
| 5174 | landing |
|
|
| 42069 | Ponder |
|
|
| 43069 | txnBot |
|
|
| 5100 | Otterscan |
|
|
| 8081 | Caddy |
|
|
|
|
Check with `lsof -i :<port>` if startup fails.
|
|
|
|
## Docker Topology
|
|
- `docker-compose.yml` has NO `depends_on`. Service ordering is handled by `scripts/dev.sh`.
|
|
- Startup phases: anvil+postgres → bootstrap → ponder → webapp/landing/txn-bot → caddy → smoke test.
|
|
- Shared bootstrap: `scripts/bootstrap-common.sh` (sourced by both local dev and CI).
|
|
- 20GB disk limit enforced. `dev.sh stop` auto-prunes. Named volumes for `node_modules`.
|
|
- All services have log rotation (30MB max per container) and PostgreSQL WAL limits configured.
|
|
|
|
## kraiken-lib Build
|
|
- Run `./scripts/build-kraiken-lib.sh` before `docker-compose up` so containers mount a fresh `kraiken-lib/dist` from the host.
|
|
- `scripts/watch-kraiken-lib.sh` rebuilds on file changes (requires inotify-tools) and restarts dependent containers automatically.
|
|
- The dev script runs the build automatically on `start`, but manual rebuilds are needed if you change kraiken-lib while the stack is already running.
|
|
|
|
## Common Pitfalls
|
|
- **Docker disk full**: `dev.sh start` refuses to run if Docker disk usage exceeds 20GB. Fix: `./scripts/dev.sh stop` (auto-prunes) or `docker system prune -af --volumes`.
|
|
- **Stale Ponder state**: If Ponder fails with schema errors after contract changes, delete its state: `rm -rf services/ponder/.ponder/` then `./scripts/dev.sh restart --full`.
|
|
- **kraiken-lib out of date**: If services fail with import errors or missing exports, rebuild: `./scripts/build-kraiken-lib.sh`.
|
|
- **Container not found errors**: `dev.sh` expects Docker Compose v2 container names (`harb-anvil-1`, hyphens not underscores). Verify with `docker compose version`.
|
|
- **Port conflicts**: See Ports table above. Check with `lsof -i :<port>` if startup fails.
|
|
- **npm ci failures in containers**: Named Docker volumes cache `node_modules/`. If dependencies change and installs fail, remove the volume: `docker volume rm harb_webapp_node_modules` (or similar), then restart.
|
|
|
|
## Handy Commands
|
|
```bash
|
|
foundryup # update Foundry toolchain
|
|
anvil --fork-url https://sepolia.base.org # manual fork for diagnosing outside dev.sh
|
|
|
|
# inspect services while stack is running
|
|
curl http://localhost:8081/api/txn/status
|
|
curl -X POST http://localhost:8081/api/graphql \
|
|
-d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'
|
|
cast call <POOL> "slot0()" # inspect pool state
|
|
PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev # focused Ponder debugging (inside services/ponder/)
|
|
```
|