Local Setup

Prerequisites

• Node.js 22+ (LTS)
• pnpm 10+ (enabled via corepack: corepack enable)
• Docker & Docker Compose

That's it. Docker handles PostgreSQL, PostGIS, Redis, and all application services — you don't need to install any of these manually.

Quick Start (macOS / Linux)

# Clone and install
git clone <repo-url>
cd gis-data
cp .env.example .env
pnpm install

# Start everything: Docker services, migrations, admin seed
make start

make start does the following automatically:

1. Starts all Docker containers (PostgreSQL + PostGIS, Redis, API, frontend, admin, workers, docs)
2. Waits for PostgreSQL to be healthy
3. Runs database migrations
4. Seeds default admin users

Once it completes, services are available at:

• Frontend: http://localhost:8000
• API: http://localhost:8001
• Admin: http://localhost:8002
• API Docs (Swagger): http://localhost:8001/docs
• Help Docs: http://localhost:8003
• Dev Docs: http://localhost:8004

Default users created by the seed:

• Superadmin: superadmin@gis-data.work / Super@dmin2026!
• Admin: admin@gis-data.work / Adm1n@2026!

Quick Start (Windows)

Windows doesn't include make by default. You have two options:

Option A: Install Make (recommended)

Install make via one of these package managers, then use the same make start command as above:

With Chocolatey:

choco install make

With Scoop:

scoop install make

With winget:

winget install GnuWin32.Make

After installing, restart your terminal and use make start, make dev, etc. as normal.

Option B: Run commands manually (PowerShell)

If you prefer not to install make, run the equivalent commands directly:

# Clone and install
git clone <repo-url>
cd gis-data
Copy-Item .env.example .env
pnpm install

# Start Docker services
docker compose up -d

# Wait for PostgreSQL to be ready
Write-Host "Waiting for postgres..."
do { Start-Sleep -Seconds 1 } while (-not (docker compose exec postgres pg_isready -U gis -d gis_data 2>$null))
Write-Host "Postgres is ready."

# Run migrations and seed
$env:DB_PORT = "5434"; pnpm migration:run
cd api
$env:DB_PORT = "5434"; pnpm seed:admin
cd ..

Other common commands for Windows (without Make):

Make command	PowerShell equivalent
make start	See above
make restart	docker compose down; then run the start commands above
make dev	Start-Process pnpm -ArgumentList "dev:frontend"; pnpm dev:api
make lint	pnpm lint
make format	pnpm format
make test	cd api; pnpm test
make docker-up	docker compose up -d
make docker-down	docker compose down
make docker-logs	docker compose logs -f

WSL (Windows Subsystem for Linux)

If you use WSL, you can follow the macOS / Linux instructions directly. WSL provides a full Linux environment with make available out of the box. Make sure Docker Desktop is configured to use the WSL 2 backend.

Makefile Commands

The Makefile provides shortcuts for common tasks. Run make help to see all available commands.

Command	Description
make start	Start Docker + migrations + seed (full setup)
make restart	Stop everything and start fresh
make dev	Start frontend + API in parallel (local, no Docker)
make dev-frontend	Start Vite dev server (:8000)
make dev-api	Start NestJS in watch mode (:8001)
make build	Build all packages
make lint	Lint all packages
make format	Format all packages
make test	Run all API tests (unit + e2e)
make test-frontend	Run frontend tests
make storybook	Start Storybook on :6006
make docker-up	Start Docker containers
make docker-down	Stop Docker containers
make docker-logs	Follow Docker logs
make docker-rebuild	Rebuild and restart all containers
make migrate-run	Run pending migrations
make migrate-revert	Revert last migration
make seed-admin	Seed admin users
make clean	Remove build artifacts and node_modules

Environment Variables

Copy .env.example to .env before starting. The defaults work out of the box with Docker.

API & microservices (.env at project root)

Variable	Default	Description
DB_HOST	localhost	PostgreSQL host
DB_PORT	5434	PostgreSQL port (Docker maps 5434:5432)
DB_USERNAME	gis	Database user
DB_PASSWORD	gis_secret	Database password
DB_DATABASE	gis_data	Database name
API_PORT	8001	API server port
REDIS_HOST	localhost	Redis host
REDIS_PORT	6379	Redis port (Docker maps 6380:6379)

Optional:

Variable	Default	Description
DATABASE_URL	—	Full connection string (overrides individual DB_* vars)
DB_SSL	false	Enable SSL for database connection
REDIS_PASSWORD	—	Redis password (used in Railway/production)
JWT_SECRET	change-me-in-production	JWT signing secret (HMAC)
JWT_EXPIRES_IN	4h	JWT token expiration
LOGIN_THROTTLE_LIMIT	5	Login attempts per minute (per IP)
THROTTLE_LIMIT	30	Default rate limit (requests / THROTTLE_TTL)
THROTTLE_TTL	60000	Throttle window in ms
RESEND_API_KEY	—	Resend API key for transactional email
RESEND_FROM	—	Sender email address (e.g. GIS Data <noreply@gis-data.work>)
FRONTEND_URL	http://localhost:8000	Used to build password-reset and invite links in emails
TILESERV_DB_PASSWORD	tileserv_secret	Password for the SELECT-only tileserv Postgres role created/updated in migration 17. Read by both pg_tileserv and the migration.

Frontend & admin (root .env, VITE_* vars)

Variable	Description
VITE_MAPBOX_ACCESS_TOKEN	Mapbox access token (public token is fine for web)
VITE_MAPBOX_STYLE	Mapbox style URL (optional; defaults to mapbox://styles/mapbox/streets-v12)
VITE_PUBLIC_APP_URL	Public app URL (used in cookie policy / legal pages)
API_URL	Vite proxy target for /api (default http://localhost:8001)
TILESERV_URL	Vite proxy target for /tiles (default http://localhost:7800; Docker uses http://tileserv:7800)

The frontend and admin Vite configs set envDir: '..', so only VITE_* variables from the root .env are exposed to the browser. API_URL and TILESERV_URL are consumed by the dev-server proxy, not the browser.

Manual Setup (without Docker)

If you prefer running services directly on your machine instead of Docker, you'll need to install and configure the following yourself:

• PostgreSQL 16 with PostGIS 3.4 extension
• Redis 7+

1. Set Up PostgreSQL

Create a database with PostGIS:

CREATE DATABASE gis_data;
\c gis_data
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

For tests, create a separate database:

CREATE DATABASE gis_data_test;
\c gis_data_test
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

2. Configure Environment

cp .env.example .env

Update the DB_* and REDIS_* variables to match your local installations.

3. Run Migrations & Seed

pnpm migration:run
pnpm seed:admin

4. Start Development Servers

# Start API (port 8001)
pnpm dev:api

# Start Frontend (port 8000) — in a separate terminal
pnpm dev:frontend

# Start Admin (port 8002) — in a separate terminal
pnpm dev:admin

Or use the Makefile shortcut:

make dev  # Starts frontend + API in parallel

pnpm Commands Reference

These commands work on all platforms regardless of make availability.

Root Commands

Command	Description
pnpm dev:frontend	Vite dev server on :8000
pnpm dev:api	NestJS watch mode on :8001
pnpm dev:admin	Admin dev server on :8002
pnpm dev:help	User docs dev server
pnpm dev:docs	Dev docs dev server
pnpm build	Build all packages
pnpm lint	Lint all packages
pnpm format	Format all packages
pnpm storybook	Storybook on :6006

Docker Commands

Command	Description
pnpm docker:up	Start all containers
pnpm docker:down	Stop all containers
pnpm docker:logs	Follow all container logs
pnpm docker:remove	Remove containers, volumes, and images

Database Commands

Command	Description
pnpm migration:run	Run pending migrations
pnpm migration:generate	Generate migration from entity changes
pnpm migration:revert	Rollback last migration
pnpm seed:admin	Create default admin/superadmin users
pnpm backfill	Seed historical data

Per-Package Commands (run from frontend/ or api/)

Command	Description
pnpm lint:fix	Auto-fix lint issues
pnpm format:check	Check formatting
pnpm tsc-check	Type-check (frontend only)
pnpm test	Run all tests
pnpm test:unit	Unit tests only
pnpm test:e2e	E2E tests only

Pre-commit Hooks

Husky runs automatically on every commit:

1. lint-staged — lints changed .ts and .vue files, builds API if API files changed
2. Frontend type-check — runs vue-tsc --noEmit

If a commit fails, fix the reported issues before committing again. Do not use --no-verify to bypass hooks.