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

# API Setup

> Set up api-events for local development

This guide covers setting up the Soundcheck API (`api-events`) for local development.

## Prerequisites

| Tool | Purpose | Installation |
| - | - | - |
| Docker Desktop | Postgres, Azurite, Clerk emulator | [Download](https://www.docker.com/products/docker-desktop) |
| Node.js 20+ | Encore.ts runtime | Devcontainer or [nodejs.org](https://nodejs.org) |
| npm 11.15+ | Package manager | Upgraded by repo CI scripts |

> [!NOTE]
>
> Encore CLI is required for `npm run dev:emulator`. The devcontainer image includes it; otherwise install from [encore.dev](https://encore.dev/docs/ts/install).

***

## Quick start

**1. Install dependencies**

```bash theme={null}
cd api-events && npm install
```

**2. Start shared infra**

```bash theme={null}
npm run dev:infra
```

Starts Postgres (`:5433`), Azurite (`:10000`), and Clerk emulator (`:4711`) from `dev/docker-compose.yml`.

**3. Migrate and seed (first time)**

```bash theme={null}
cd api-events
export DATABASE_URL='postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public'
npm run db:migrate
npm run db:seed:demo-full
docker compose -p api -f dev/docker-compose.yml restart clerk-emulator
```

**4. Start api-events**

```bash theme={null}
cd api-events && npm run dev:emulator
```

**5. Verify it's running**

```bash theme={null}
curl http://localhost:4000/health
```

For full-stack web dev, also run `cd web && npm run dev:emulator` (proxies to Encore on `:4000`). See `.agents/skills/local-clerk-emulator/SKILL.md`.

***

## Shared infra (`dev:infra`)

```bash theme={null}
# Repo root — Postgres + Azurite + Clerk emulator (no Encore container)
npm run dev:infra

# Stop
docker compose -p api -f dev/docker-compose.yml down
```

| Service | Port |
| - | - |
| Postgres | 5433 |
| Azurite | 10000 |
| Clerk emulator | 4711 |

***

## Environment variables

`npm run dev:emulator` sets the documented local env (Clerk emulator URLs, stub providers, `DATABASE_URL`). For manual runs:

```env theme={null}
ENVIRONMENT=development
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public
CLERK_SECRET_KEY=sk_test_emulate
CLERK_API_BASE_URL=http://localhost:4711
CLERK_WEBHOOK_SECRET=whsec_c291bmRjaGVjay1sb2NhbC1jbGVyay13ZWJob29r
```

Provider stubs (`TWILIO_USE_STUB_SMS`, `SENDGRID_USE_STUB_EMAIL`, etc.) default to on in `dev:emulator`. See [api-events operations](https://docs.soundchecklive.io/engineering/backend/api-events-operations.md) for the full secrets inventory.

***

## Database access

| Property | Value |
| - | - |
| Host | localhost |
| Port | 5433 |
| Database | soundcheck |
| User | postgres |
| Password | postgres |

```bash theme={null}
psql -h localhost -p 5433 -U postgres -d soundcheck
```

| Port | Purpose |
| - | - |
| 5432 | Reserved for native PostgreSQL |
| 5433 | Docker Postgres (`dev:infra`) |
| 5434 | Integration/e2e test database |

***

## Troubleshooting

> [accordion] Port 4000 already in use
>
> ```bash theme={null}
> lsof -ti:4000
> lsof -ti:4000 | xargs kill -9
> ```
>
> Or run Encore on another port: `encore run --port=4001`

> [accordion] Database connection refused
>
> Ensure infra is running:
>
> ```bash theme={null}
> npm run dev:infra
> docker compose -p api -f dev/docker-compose.yml ps
> ```

> [accordion] Clerk sign-in works but API returns 401
>
> Restart the emulator after seeding and confirm `npm run dev:emulator` (not raw `encore run` without emulator env). See [local Clerk emulator runbook](https://github.com/soundchecklive/soundcheck-mobile-app/blob/main/api/README.md#fully-local-clerk-development).

> [accordion] Prisma client errors
>
> Regenerate after schema changes:
>
> ```bash theme={null}
> cd api-events && npm run prisma:generate
> ```

***

## Next steps

> [card] [Profiles](https://docs.soundchecklive.io/engineering/backend/profiles.md)
>
> Local infra and ephemeral profiles

> [card] [Database](https://docs.soundchecklive.io/engineering/backend/database.md)
>
> Schema, migrations, and seeding


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.