Skip to content
HandoverKey

Quick Start

Get the full stack running locally in under five minutes.

Prerequisites

  • Node.js 22+
  • npm 9+
  • Docker (for PostgreSQL and Redis)

Setup

  1. Clone and install

    Terminal window
    git clone https://github.com/HandoverKey/HandoverKey.git
    cd HandoverKey
    npm install

  2. Copy env files

    Terminal window
    cp apps/api/.env.example apps/api/.env
    cp apps/web/.env.example apps/web/.env

  3. Generate required secrets

    Open apps/api/.env and fill in the two required secrets:

    Terminal window
    JWT_SECRET=$(openssl rand -base64 64)
    ACTIVITY_HMAC_SECRET=$(openssl rand -base64 64)

  4. Start infrastructure and run migrations

    Terminal window
    npm run docker:up
    npm run db:migrate

  5. Start the dev servers

    Terminal window
    npm run dev

Local URLs

ServiceURL
Web apphttp://localhost:5173
APIhttp://localhost:3001/api/v1
WebSocketws://localhost:3001/ws

What’s next?

  • Set up SMTP so email reminders and handover notifications work
  • Review the Security Model before storing real secrets
  • Read the full Deployment Guide for production setup