Contributor Setup
Parcelis is a pnpm/Turbo monorepo. This guide gets the web app, API, and local services running on your machine.
Existing PostgreSQL 16 development databases must follow Upgrade PostgreSQL 16 to 18 before running pnpm dev or refreshing services. New installations use PostgreSQL 18.
Requirements
| Tool | Required version |
|---|---|
| Node.js | 24.19.0 |
| pnpm | 12 |
| Docker Desktop | Current stable release |
Confirm your local runtime before continuing:
node --version
pnpm --version
First-time setup
pnpm install
cp .env.example .env
# Set a unique, 12+ character SEED_ADMIN_PASSWORD in .env
docker compose -f docker-compose-dev.yml up -d
pnpm db:generate
pnpm db:migrate
pnpm db:seed
pnpm dev
pnpm dev runs the web app, API, and React Email previews with hot reload. Docker provides nginx,
PostgreSQL, pgAdmin, MinIO, and the one-time MinIO initialization job.
Documentation is maintained and deployed separately in parcelis/parcelis-docs. pnpm dev does not start a documentation server. Legacy application /docs links redirect to the hosted site.
Local URLs
Use nginx as the usual entry point:
| Service | URL |
|---|---|
| Web app | http://localhost |
| Documentation | https://docs.parcelis.dev/ |
| API | http://localhost/api/v1 |
| React Email previews | http://templates.localhost/ |
The apps and services are also available directly:
| Service | Address |
|---|---|
| Web app | http://localhost:30000 |
| API | http://localhost:40010 |
| React Email previews | http://localhost:30001 by default; use the port printed by pnpm dev |
| PostgreSQL | localhost:54320 |
| pgAdmin | http://localhost:8000 |
| MinIO API | http://localhost:9001 |
| MinIO console | http://localhost:9010 |
pgAdmin uses admin@parcelis.dev / parcelis. The local Parcelis database is preconfigured; its password is parcelis.
Database workflow
Prisma commands run through pnpm db:* load the root .env. If DATABASE_URL is unset, the API uses postgresql://parcelis:parcelis@localhost:54320/parcelis?schema=public only when NODE_ENV is development or test. Other environments require an explicit PostgreSQL URL; empty or invalid values fail startup.
After pulling schema changes, run:
pnpm db:migrate
pnpm db:seed
Useful commands
pnpm typecheck
pnpm lint
pnpm dev:services:refresh
pnpm dev:services:refresh recreates nginx, PostgreSQL, and MinIO while preserving their volumes, then reruns MinIO initialization. Stop an existing app watcher with Ctrl+C before starting another pnpm dev process.
For the complete contributor workflow, including commit conventions and production-style deployment, see the contributing guide.