Local development

How to run the foraging platform and this docs site on a developer machine.

Prerequisites

• Node.js 24 (matches client/Dockerfile and CI)
• PostgreSQL reachable via DATABASE_URL (local or hosted)
• npm (lockfiles are npm; each package has its own package-lock.json)

Install

From the repo root:

# Client
cd client && npm ci && cd ..

# Server (postinstall runs prisma generate)
cd server && npm ci && cd ..

# Docs site (optional for app work)
cd docs-site && npm ci && cd ..

:::tip Prisma version Use server/package.json: Prisma 6.19.1. The root package.json still lists Prisma ^5.22 for legacy tooling — do not treat root as authoritative for the server. :::

Environment (names only)

Validated in server/src/utils/env.js (Zod). Required:

Name	Meaning
ORIGIN_URL	Allowed browser origin (URL) for CORS / cookies
WS_PORT	HTTP + Socket.IO listen port (digits)
DATABASE_URL	Prisma Postgres connection string

Optional: TRUST_PROXY_HOPS — non-negative hop count for Express trust proxy (omit to use server defaults).

Put values in server/.env locally. Never commit secrets.

Client (dev only): DEV_SERVER_ORIGIN — where Next rewrites API/socket traffic (default http://localhost:3001). In Docker Compose dev this is set to http://server:4000.

Run without Docker

# From repo root — client + server together
npm run dev

# Or separately
npm run dev:client   # Next.js (typically :3000)
npm run dev:server   # Express + Socket.IO on WS_PORT

In development, client/next.config.mjs rewrites:

• /api/* → DEV_SERVER_ORIGIN
• /socket.io/* → DEV_SERVER_ORIGIN
• /health → DEV_SERVER_ORIGIN

Production builds emit no rewrites; host Nginx proxies those paths.

Database

cd server
npx prisma generate
npx prisma migrate dev      # create/apply migrations in development
# npx prisma migrate deploy  # used by container entrypoint in prod/test
npx prisma studio            # optional GUI

Schema: server/prisma/schema.prisma.

Run with Docker Compose (dev)

docker compose -f docker-compose.dev.yml up --build

Service	Host port	Container
Client	39000 → 3000	npm run dev, DEV_SERVER_ORIGIN=http://server:4000
Server	39001 → 4000	npm run dev, WS_PORT=4000, ORIGIN_URL=http://localhost:3000, env_file: ./server/.env

Open the app at http://localhost:39000.

Docs site

cd docs-site
npm run start    # http://localhost:3100  (port avoids clashing with Next :3000)
npm run build
npm run serve    # production build on :3100

docs-site/ is an independent npm project. It is not part of root npm run dev / npm run build.

:::note node_modules on this host If the project filesystem cannot create symlinks, install under /root/eacmlab-docs-site/ and bind-mount into docs-site/node_modules (see CLAUDE.md). :::

Useful checks

curl -s http://localhost:3001/health   # bare server (WS_PORT)
# or via Next rewrite / Docker client proxy:
curl -s http://localhost:3000/health
cd client && npm run lint
cd server && npm run lint