Run Server, App, and Docs

Docker is the default runtime. It starts MongoDB, the API server, the app, and the event poller.

Docker stack

Start services

pnpm docker:up

Use pnpm docker:build after dependency, contract artifact, or Dockerfile changes.

Check containers

docker ps

You should see MongoDB, server, and app containers.

Check the API

curl http://localhost:8293/

The Docker server runs with the event poller enabled.

App and docs

Goal	Command	URL
App in Docker	`pnpm docker:up`	`http://localhost:3000`
Local app dev	`pnpm app:dev`	`http://localhost:3000`
Docs	`pnpm docs:dev`	`http://localhost:3001`
Docs build	`pnpm docs:build`	None

Use local app dev for wallet mint work that depends on NEXT_PUBLIC_* env vars. The API-first guide works with the Docker app/server path.

Local server dev

Use this only when editing server code:

pnpm docker:down
docker compose up -d mongodb
pnpm dev

pnpm dev starts the API with hot reload and the poller. Run pnpm app:dev in another terminal if you also need the app outside Docker.

What is the event poller?

The event poller watches the blockchain for contract events (issuances, transfers, cancellations, and so on) and writes them into MongoDB. It is what keeps the off-chain database in sync with onchain state — if it isn’t running, your history endpoint will go stale.

Three commands wrap it differently:

pnpm dev — server with the event poller, hot reload on. Use this for local development.
pnpm prod — server only, no poller. Use this when you run the poller as a separate process.
pnpm prod-poller — standalone poller against finalized blocks. Pair this with pnpm prod in production so the poller can restart without taking the API with it.

For local development, pnpm dev already includes the poller. In production, run the server and the poller as two separate processes.

A healthy boot logs roughly:

✅ Mongo connected
✅ Express listening on :8293
⏳ Poller starting (finalized-only=false)

Fixes

If you don’t see changes that you pushed in your code on the app or in the server, rebuild docker containers (since they don’t have hot reloading).

docker compose up -d --build app server

Symptom	Check
`EADDRINUSE`	Another process uses `PORT=8293`.
History does not update	Docker server is running, or run `pnpm prod-poller`.
Contract reads fail	Issuer has `deployed_to`; `.env` points at Plume Mainnet.
Frontend API fails	`NEXT_PUBLIC_API_URL=http://localhost:8293`.

Next: Register the factory, then create an issuer.

Setup Deploy Factory