Run Server, App, and Docs
The local stack is MongoDB, the API with its event poller, and the product app. Docker runs the first two; the app runs on your machine.
| Order | Process | Why it runs |
|---|---|---|
| 1 | MongoDB | Stores the offchain mirror (host port 27027). |
| 2 | API and event poller | Serves reads and server-signed writes, and copies confirmed contract events into MongoDB. |
| 3 | Product app | Connects the issuer’s wallet for direct writes. |
| 4 | Docs (optional) | Serves this site locally. |
Start MongoDB and the API
SKIP_APP=1 pnpm bootstrap
curl http://localhost:8293/The API replies with a welcome message. After you change server code, the server image, or .env, rebuild the API with docker compose up -d --build server. pnpm docker:build also starts the Docker app on port 3000.
Start the app and docs
| Goal | Command | URL |
|---|---|---|
| Product app | pnpm app:dev | http://localhost:3000/app |
| Docker app preview (no hot reload) | pnpm docker:up | http://localhost:3000 |
| Docs | pnpm docs:dev | http://localhost:3001 |
pnpm app:dev reads app/.env.local. The Docker preview reads the root .env, so keep their NEXT_PUBLIC_* values in sync.
Run the API on your machine
For hot reload while you work on the server:
docker compose stop server
pnpm devThis frees port 8293 and runs the API and the poller from your checkout. MongoDB keeps running in Docker.
Event poller
The poller copies confirmed contract events into MongoDB, which keeps history and sync flags current. pnpm dev and the Docker server run it. pnpm prod starts the API without it; run pnpm prod-poller alongside, which reads only finalized blocks and lags Plume by about 20 minutes.
The poller follows only issuers registered in this database. Load from wallet in the app lists companies already registered here; it doesn’t import them from the chain. To bring an existing cap table into a fresh database, see Register Issuer.
Troubleshooting
| Symptom | Fix |
|---|---|
pnpm dev stops with Unable to locate .env | Run it from a checkout with a root .env (cp .env.example .env), or set DATABASE_URL and PORT in the environment. |
| The wallet dialog lists no wallets | Install a browser extension wallet such as Rabby or MetaMask. |
EADDRINUSE on port 8293 or 3000 | Find the process with lsof -i :3000. If it’s the Docker app preview, run docker compose stop app. |
| Another app expects MongoDB on 27017 | TAP uses host port 27027. Point DATABASE_URL at 27027 and stop any old container still bound to 27017 with docker compose stop. |
| History never updates | Check that the poller is running and the issuer has a deployed_to address. If the logs repeat Stakeholder does not exist, register that stakeholder with POST /stakeholder/register-onchain using its onchain id. |
Repeated Connection ended lines from MongoDB | Normal idle connection churn. A real failure logs Error connecting to Mongo. |
Can't resolve '@tap/units' on port 3000 | The Docker app image is stale. Rebuild it with pnpm docker:build, or stop it and use pnpm app:dev. |
| The app can’t reach the API | Set NEXT_PUBLIC_API_URL=http://localhost:8293 in app/.env.local. |
| The app and API use different factories | Make MongoDB factories and NEXT_PUBLIC_FACTORY_ADDRESS match. See Deploy the Factory. |
Next: deploy or register a factory.