Skip to Content
DevelopmentRun Server

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.

OrderProcessWhy it runs
1MongoDBStores the offchain mirror (host port 27027).
2API and event pollerServes reads and server-signed writes, and copies confirmed contract events into MongoDB.
3Product appConnects the issuer’s wallet for direct writes.
4Docs (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

GoalCommandURL
Product apppnpm app:devhttp://localhost:3000/app 
Docker app preview (no hot reload)pnpm docker:uphttp://localhost:3000 
Docspnpm docs:devhttp://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 dev

This 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

SymptomFix
pnpm dev stops with Unable to locate .envRun 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 walletsInstall a browser extension wallet such as Rabby or MetaMask.
EADDRINUSE on port 8293 or 3000Find the process with lsof -i :3000. If it’s the Docker app preview, run docker compose stop app.
Another app expects MongoDB on 27017TAP uses host port 27027. Point DATABASE_URL at 27027 and stop any old container still bound to 27017 with docker compose stop.
History never updatesCheck 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 MongoDBNormal idle connection churn. A real failure logs Error connecting to Mongo.
Can't resolve '@tap/units' on port 3000The 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 APISet NEXT_PUBLIC_API_URL=http://localhost:8293 in app/.env.local.
The app and API use different factoriesMake MongoDB factories and NEXT_PUBLIC_FACTORY_ADDRESS match. See Deploy the Factory.

Next: deploy or register a factory.

Last updated on