---
title: Local development
description: Run the stores in Docker and the services from the repository.
---

1. **Configuration**

    Copy the example environment of every service:

    ```bash
    for app in api api-ingest mcp worker-errors worker-jobs web; do cp apps/$app/.env.example apps/$app/.env; done
    ```

    Set `BETTER_AUTH_SECRET` in `apps/api/.env` to at least 32 characters: `openssl rand -hex 32`. Leave optional variables out rather than empty: `KEY=` fails validation. Every variable is in [Configuration](/self-hosting/configuration).

2. **Stores**

    ```bash
    docker compose up -d
    ```

    PostgreSQL on 5432, ClickHouse on 8123, Valkey for state on 6379 and cache on 6380, RustFS on 9000, all on `127.0.0.1` only. A root `.env` overrides ports and credentials.

3. **Dependencies and schema**

    ```bash
    bun install
    bun run --cwd apps/api db:migrate
    bun run --cwd apps/api-ingest db:migrate
    ```

4. **Services**

    Start each in its own terminal: `bun run dev:api-ingest`, `dev:api`, `dev:worker-errors`, `dev:worker-jobs`, `dev:web`, and `dev:mcp` for AI assistants.

    | Service      | URL                                 |
    | ------------ | ----------------------------------- |
    | `web`        | `https://openperf.localhost`        |
    | `api`        | `https://api.openperf.localhost`    |
    | `api-ingest` | `https://ingest.openperf.localhost` |
    | `mcp`        | `https://mcp.openperf.localhost`    |

    Services run behind [portless](https://github.com/vercel-labs/portless). The first run asks for `sudo` once to bind port 443 and trust its certificate. Node processes outside portless that call these URLs need `NODE_EXTRA_CA_CERTS=~/.portless/ca.pem`. `PORTLESS=0` runs a service on its own port: then point the origins in its `.env` at `http://localhost` and remove `BETTER_AUTH_COOKIE_DOMAIN`.

- `bun run seed --project <id|slug>` fills a project with demo telemetry. Set `INGEST_RATE_LIMIT_PER_MINUTE=0` and `INGEST_IP_RATE_LIMIT_PER_MINUTE=0` in `apps/api-ingest/.env` so it isn't throttled.
- `bun run dev:docs` serves this site on port 4300.