Run Server, App, and Docs
Healthy local product stack: Docker for Mongo + API + poller, host Next for the wallet UI.
| Start order | Process | Why it runs |
|---|---|---|
| 1 | MongoDB | Persists the local OCF mirror. |
| 2 | API + poller | Serves reads/automation and mirrors confirmed events. |
| 3 | Product UI | Connects the issuer ADMIN wallet for direct writes. |
| 4 | Docs, optional | Serves this reference locally. |
Docker (Mongo + API)
Start services
SKIP_APP=1 pnpm bootstrap # Mongo + API + poller; leaves :3000 for host pnpm app:dev
# Include the Docker app preview on :3000: pnpm bootstrap (or pnpm docker:up)Rebuild after app source, env, or Dockerfile changes: pnpm docker:build. The Docker app is next start (no file watcher). Wallet work still prefers host pnpm app:dev (app/.env.local).
Check the API
curl http://localhost:8293/The Docker server runs with the event poller enabled.
App and docs
| Goal | Command | URL |
|---|---|---|
| Product UI (preferred) | pnpm app:dev | http://localhost:3000/app |
| App in Docker (optional) | pnpm docker:up | http://localhost:3000 |
| Docs | pnpm docs:dev | http://localhost:3001 |
Wallet mint/manage needs app/.env.local (NEXT_PUBLIC_*). Docker app reads root .env interpolation from compose — keep both aligned if you use Docker app.
Local server hot-reload
docker compose stop server
pnpm devdocker compose stop server frees port 8293 and leaves Mongo running. pnpm dev starts the API with hot reload and the poller.
Event poller
The poller watches contract events and writes them into MongoDB. Without it, history and mirrored positions go stale.
| Command | Behavior |
|---|---|
pnpm dev | API + poller, hot reload |
pnpm prod | API only |
pnpm prod-poller | Standalone finalized-only poller |
A fresh Mongo does not auto-import every historical issuer on Plume. Use mint, Load from wallet, or issuer register/reindex for companies you care about.
Troubleshooting
| Symptom | Check |
|---|---|
Can't resolve '@tap/units' on :3000 | Docker app image must COPY packages/; or stop Docker app and run pnpm app:dev |
| Empty connect modal / no wallets | Install a browser extension wallet (Rabby, MetaMask, etc.) — EIP-6963, no cloud key needed |
EADDRINUSE | Port 8293 or 3000 already in use (lsof -i :3000) |
| Other app wants Mongo 27017 | TAP publishes 27027. Host DATABASE_URL must use 27027. docker compose stop the container still bound to 27017. |
| History does not update | Poller running; issuer registered with deployed_to |
| Frontend API fails | NEXT_PUBLIC_API_URL=http://localhost:8293 (host-reachable) |
| Factory misaligned | Mongo factories vs NEXT_PUBLIC_FACTORY_ADDRESS |
Next: Deploy your transfer-agent factory, then create an issuer.