Local development

Local development runs three processes: the Go API, the portal dev server, and (optionally) the marketing site, with PostgreSQL and SuperTokens in Docker.

Prerequisites

Go 1.24+, Node 22+, Docker
Task for the repo’s task runner commands
Air for Go live-reload (optional but recommended)

docker-compose.local-st.yml self-hosts both PostgreSQL and SuperTokens, so you can run everything locally without creating any external accounts:

git clone https://github.com/hackutd/harp
cd harp
docker compose -f docker-compose.local-st.yml up -d

Google Cloud Storage is optional in local dev; leaving the bucket unset disables it. Email, web push, and Apple Wallet are similarly optional.

Run the backend

task migrate-up   # apply database migrations
task seed         # optional: seed development data
air               # Go API on :8080 with live reload

Run the portal

cd client/portal
npm install
npm run dev       # http://localhost:3000

The portal owns port 3000. It’s pinned there by FRONTEND_URL and the SuperTokens website domain.

Run the marketing site (optional)

cd client/marketing
npm install
npm run dev       # http://localhost:3001

It needs HARP_API_BASE_URL and HARP_PUBLIC_API_KEY set (matching the backend’s PUBLIC_API_KEY); without them the page renders setup instructions instead of live data.

Git hooks

If you plan to commit, enable the repo’s hooks once per clone:

task setup-hooks

See Contributing for what they enforce.

Getting Started

Projects

Prerequisites

Run the backend

Run the portal

Run the marketing site (optional)

Git hooks

​Prerequisites

​The zero-signup path

​Run the backend

​Run the portal

​Run the marketing site (optional)

​Git hooks

Prerequisites

The zero-signup path

Run the backend

Run the portal

Run the marketing site (optional)

Git hooks