Local Development Setup
Step-by-step guide for configuring a VeriWorkly development environment.
Local Development Setup
This guide covers setting up a local development environment for contributors and anyone customising the platform.
Prerequisites
- Node.js — version 20.19.0 or higher (Node.js 22 supported).
- npm — the repository uses npm workspaces; other package managers are not configured.
- PostgreSQL — required for anything that touches the API. Neon works well as a managed option.
- Redis — required by the backend. Sessions, rate limiting, ATS and import quotas, buffered view counts, and job locks all use it. The rate limiter has a bounded in-memory fallback, but auth session storage does not, so the API is not reliably usable without Redis.
Frontend-only work needs neither
If you are editing marketing pages, the design system, or resume templates, you can run
apps/site or apps/studio alone without PostgreSQL or Redis. Only features that call the API
(login, sync, AI, ATS, publishing) will be unavailable.
Installation
Fork and clone
-
Fork the VeriWorkly repository to your account.
-
Clone your fork:
git clone https://github.com/YOUR_USERNAME/veriworkly.git cd veriworkly
apps/portfolio template library
apps/portfolio/template-library is a git submodule pointing at the private
VeriWorkly/portfolio-templates repository. If you have access, initialise it with
git submodule update --init --recursive. If you do not have private repository access,
you can scaffold stand-in mock templates to build and run apps/portfolio locally by running:
node scripts/mock-template-library.mjs.
Configure the upstream remote
Track the original repository so you can pull future updates. All work is based on master:
git remote add upstream https://github.com/VeriWorkly/veriworkly.git
git checkout master
git pull upstream masterInstall dependencies
Run once from the repository root — npm workspaces installs every application:
npm installConfigure environment variables
Copy the example files you need:
cp .env.example .env
cp apps/server/.env.example apps/server/.env
cp apps/site/.env.example apps/site/.env
cp apps/studio/.env.example apps/studio/.env
cp apps/portfolio/.env.example apps/portfolio/.env
cp apps/docs-platform/.env.example apps/docs-platform/.env
cp apps/blog-platform/.env.example apps/blog-platform/.envMinimum values for a working full-stack local environment:
| Variable | Where | Notes |
|---|---|---|
DATABASE_URL | apps/server/.env | PostgreSQL connection string. |
REDIS_URL | apps/server/.env | Defaults to redis://localhost:6379. |
AUTH_SECRET | server and each frontend | Must be identical everywhere. |
AUTH_BASE_URL | apps/server/.env | Defaults to http://localhost:8080. |
NEXT_PUBLIC_BACKEND_URL | each frontend | Defaults to http://localhost:8080/api/v1. |
ADMIN_EMAIL | server and frontends | The account auto-provisioned as admin on boot. Also unlocks portfolio publishing and checkout locally. |
Everything else — AI, Dodo Payments, Cloudflare R2, GitHub sync, SMTP — is optional in development. Without them, the corresponding features return errors, but the rest of the app runs. See Environment Variables for the full reference.
Initialise the database
Push the Prisma schema and generate the client:
npm run db:push
npm run db:generateBoth scripts proxy to the @veriworkly/server workspace.
Start the development servers
Option A — a single workspace
npm run dev # marketing site → http://localhost:3000
npm run dev:studio # document builder → http://localhost:3001
npm run dev:docs # documentation → http://localhost:3002
npm run dev:blog # blog → http://localhost:3003
npm run dev:portfolio # portfolio builder → http://localhost:3004
npm run dev:server # Express API → http://localhost:8080npm run dev with no suffix starts the marketing site only.
Option B — everything at once
npm run dev:allThis runs the dev script in every workspace concurrently, including the API.
Validate before committing
# ESLint across the monorepo
npm run lint
# Prettier formatting
npm run format:write
# Backend test suite (Vitest)
npm test -w @veriworkly/server
# Frontend contract and unit suites (Vitest)
npm run test:contracts -w @veriworkly/studio
npm run test:contracts -w @veriworkly/site
npm test -w @veriworkly/portfolio
# Preview/PDF parity — boots the app and a real Chromium, takes minutes.
# Run it when you have touched a resume or cover letter template.
npm run test:parity -w @veriworkly/studio
# Verify every workspace builds
npm run buildThere is no root `npm test`
The repository root does not define a test script. Run the workspace-scoped commands above
instead — npm test from the root will fail.
Verifying your environment
| Service | URL |
|---|---|
| Marketing site | http://localhost:3000 |
| Studio (document builder) | http://localhost:3001 |
| Documentation | http://localhost:3002 |
| Blog | http://localhost:3003 |
| Portfolio builder | http://localhost:3004 |
| API liveness | http://localhost:8080/api/v1/health |
| API readiness | http://localhost:8080/api/v1/health/ready |
/health is a lightweight liveness check that does not touch external services. /health/ready
actively probes PostgreSQL and Redis and is the endpoint to use when confirming your database and
cache connections work. See Service Status.
Useful workspace scripts
| Command | Effect |
|---|---|
npm run db:migrate | Create and apply a Prisma migration. |
npm run db:studio | Open Prisma Studio against your database. |
npm run generate:api | Bundle apps/docs-platform/specs/openapi.yaml and regenerate the API reference MDX pages. Runs automatically before the docs dev and build, so you rarely need it directly. |
npm run sync:github -w @veriworkly/server | Run the GitHub statistics sync once, outside the cron schedule. |
npm run seed:roadmap -w @veriworkly/server | Seed public roadmap data. |
npm run seed:changelog -w @veriworkly/server | Seed changelog entries. |