> ## 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.

# Development Profiles

> Local infra and ephemeral service profiles for api-events development

Local development splits **shared infra** (Postgres, Clerk emulator, Azurite) from the **Encore API** (run on the host via `npm run dev:emulator`). External providers are stubbed by default for safety.

## Profile summary

| Profile | How to start | Database | External services | Use case |
| - | - | - | - | - |
| **Dev infra** (default) | `npm run dev:infra` | Persistent (`:5433`) | Stubbed via `dev:emulator` env | Day-to-day API + web dev |
| **Ephemeral** | `docker compose -p api -f dev/docker-compose.yml --profile ephemeral up -d` | tmpfs (resets) | Stubbed | Integration/e2e isolated DB |

Encore itself is **not** containerized for local dev — run `cd api-events && npm run dev:emulator` after infra is up.

***

## Dev infra (default)

Starts Postgres, Azurite, the Clerk emulator, and the Cleo Pay emulator without any API container.

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

### What runs

| Service | Port | Notes |
| - | - | - |
| `db` | 5433 | Persistent volume |
| `azurite` | 10000 | Blob storage emulator |
| `clerk-emulator` | 4711 | Local Clerk + webhook to `:4000` |
| `cleo-pay-emulator` | 4092 | Local Cleo Pay partner API + webhook to `:4000` |

Compose file: `dev/docker-compose.yml` (project name `api`, shared with legacy Go compose volumes).

### Typical workflow

```bash theme={null}
npm run dev:infra
cd api-events && npm run db:migrate && npm run db:seed:demo-full
docker compose -p api -f dev/docker-compose.yml restart clerk-emulator
cd api-events && npm run dev:emulator
cd web && npm run dev:emulator
```

`dev:emulator` sets stub flags (`TWILIO_USE_STUB_SMS`, `NOTIFICATIONS_DRY_RUN=true`, etc.), points Clerk at `:4711`, and points Cleo Pay at `:4092`.

To exercise the member onboarding progress tracker, sign in as **Indigo Onboarding** and open `/onboarding/org?orgId=org_plo9pyQatNovhdX8kXMRd6IjarB`. The busy org seed has a 7-step flow with long titles; Indigo is mid-flow on step 4.

***

## Ephemeral profile

Isolated Postgres (and supporting stubs) that **resets on restart**. Used by api-events integration tests and CI.

```bash theme={null}
docker compose -p api -f dev/docker-compose.yml --profile ephemeral up -d
```

### Configuration

| Service | Notes |
| - | - |
| `db-ephemeral` | tmpfs Postgres — no host port (tests use `:5434` via setup script) |
| `azurite-ephemeral` | tmpfs Azurite |
| `stripe-mock-ephemeral` | Stripe mock on `:12111` |

### Use cases

* `npm run test:integration:setup` then `npm run test:integration` in api-events
* E2e / CI pipelines that need a clean database
* Running alongside dev infra (different network)

***

## Environment files

Local secrets are gitignored. `npm run dev:emulator` bakes in the documented emulator values — you usually do not need a hand-edited `.env` for the default loop.

| Source | Purpose |
| - | - |
| `api-events/scripts/dev-emulator.mjs` | Forces emulator Clerk + stub provider env |
| `dev/docker-compose.yml` | Infra service config + Clerk/Cleo webhook URLs to the host relay on `:4093` |

For deployed env inventory, see [api-events operations](https://docs.soundchecklive.io/engineering/backend/api-events-operations.md).

***

## Docker layout

```
dev/docker-compose.yml
├── db                    # Persistent Postgres (:5433) — sandbox/default/watch profiles
├── azurite               # Blob emulator (:10000)
├── clerk-emulator        # Local Clerk (:4711)
├── cleo-pay-emulator     # Local Cleo Pay partner API (:4092)
├── db-ephemeral          # tmpfs Postgres (ephemeral profile)
├── azurite-ephemeral     # tmpfs Azurite (ephemeral profile)
└── stripe-mock-ephemeral # Stripe mock (ephemeral profile)
```

Encore api-events runs on the **host** at `:4000`, not inside this compose file.
`npm run dev:emulator` also starts a webhook-only relay on `:4093` so Docker emulators can reach Clerk/Cleo webhook paths without exposing the full API.

***

## Common commands

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

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

# Ephemeral stack (tests)
docker compose -p api -f dev/docker-compose.yml --profile ephemeral up -d

# Restart Clerk after seed
docker compose -p api -f dev/docker-compose.yml restart clerk-emulator
```

***

## Troubleshooting

> [accordion] Clerk personas missing after seed
>
> Run `npm run db:seed:demo-full`, then restart `clerk-emulator`. The emulator reads `api-events/scripts/seed/manifest/local-personas.json`.

> [accordion] Port 5433 already in use
>
> Another Postgres or stale compose project may hold the port:
>
> ```bash theme={null}
> docker compose -p api -f dev/docker-compose.yml down
> lsof -ti:5433
> ```

> [accordion] Ephemeral data not persisting
>
> By design — use dev infra (`npm run dev:infra`) for persistent local data.


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