SportReserve

SportReserve is a university sports facility reservation platform for Sport Representatives, a session-scoped Sport Director, and Sport Council staff.

Prerequisites

• Node.js 24+
• Corepack with pnpm 11
• Docker with Docker Compose

Local setup

corepack enable
corepack prepare pnpm@11.17.0 --activate
pnpm install --frozen-lockfile
cp .env.example .env
docker compose up -d --wait
pnpm db:migrate
pnpm dev

The web app runs at http://localhost:3000, the API at http://localhost:3001/api/v1, and Swagger at http://localhost:3001/docs.

The repository-root .env is loaded by Docker Compose, the API, Drizzle, and the web app. The Postgres container creates the configured POSTGRES_USER and POSTGRES_DB automatically the first time its named data volume is initialized; no manual database creation is needed.

The credentials in .env.example are intentionally simple local-development defaults. The real .env is ignored by Git. These defaults must not be reused for a deployed environment, where credentials should come from the hosting platform's secret manager and the database and Redis ports should not be published publicly.

Create the first staff account

SportReserve is invitation-only, so a fresh installation needs one primary staff account before anyone can sign in or invite other users. After running the migrations, open a separate terminal in the repository root and run:

read -s INITIAL_STAFF_PASSWORD
export INITIAL_STAFF_PASSWORD
pnpm staff:create -- \
  --email staff@example.com \
  --first-name Ada \
  --last-name Okafor
unset INITIAL_STAFF_PASSWORD

After read -s INITIAL_STAFF_PASSWORD, type a password containing between 12 and 128 characters and press Enter. The password is intentionally hidden while you type. Replace the example email and names with the authorised staff member's details.

This bootstrap command creates only the first staff account. That primary staff member must invite additional staff from the staff-management page.

Docker socket permission on Linux/WSL

If Docker reports permission denied for /var/run/docker.sock, add your Linux user to the socket's docker group, then refresh the login session:

sudo usermod -aG docker "$USER"
newgrp docker
docker info

On WSL, restarting the distribution from PowerShell with wsl --shutdown is the most reliable way to refresh group membership. Also confirm Docker Desktop is running and that Settings → Resources → WSL Integration is enabled for your distribution. Do not work around the issue with chmod 666 on the Docker socket.

Port 5432 is already in use

If a locally installed PostgreSQL service already owns port 5432, either stop it before starting this project's container:

sudo systemctl stop postgresql
docker compose up -d --wait

Or keep both servers and change the Docker host port in .env:

POSTGRES_PORT=5433

DATABASE_URL is assembled from the POSTGRES_* variables, so the API and Drizzle follow the new port automatically. PostgreSQL still listens on its normal port 5432 inside the container. REDIS_URL similarly follows REDIS_PORT.

Useful commands

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm format:check
pnpm e2e
pnpm smoke
pnpm db:generate
pnpm db:migrate
pnpm db:check

The first-staff command and its required password setup are documented in Create the first staff account.

Workspace

• apps/web — Next.js App Router frontend.
• apps/api — NestJS HTTP API.
• packages/db — Drizzle schema, migration, and database types.
• packages/types — framework-neutral shared enums and transport types.