> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hackutd.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Run the full Harp stack on your machine

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](https://taskfile.dev) for the repo's task runner commands
* [Air](https://github.com/air-verse/air) for Go live-reload (optional but recommended)

## The zero-signup path

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

```bash theme={null}
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

```bash theme={null}
task migrate-up   # apply database migrations
task seed         # optional: seed development data
air               # Go API on :8080 with live reload
```

## Run the portal

```bash theme={null}
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)

```bash theme={null}
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:

```bash theme={null}
task setup-hooks
```

See [Contributing](/harp/contributing) for what they enforce.