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

# Self-Hosting

> Deploy your own Bap instance with Docker, PostgreSQL, and Redis.

## Prerequisites

* [Bun](https://bun.sh) (recommended) or Node.js
* [Docker](https://docs.docker.com/get-docker/) and Docker Compose
* API keys for the AI providers you want to use (Anthropic, OpenAI, or Google)

## Setup

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/baptistecolle/bap.git
    cd bap
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    bun install
    ```
  </Step>

  <Step title="Start local services">
    This starts PostgreSQL, Redis, and MinIO (S3-compatible storage):

    ```bash theme={null}
    docker compose -f docker/compose/dev.yml up -d
    ```
  </Step>

  <Step title="Configure environment variables">
    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `/.env` and fill in your API keys and configuration. At minimum you need:

    * `DATABASE_URL` -- PostgreSQL connection string
    * `REDIS_URL` -- Redis connection string
    * `ANTHROPIC_API_KEY` -- For Claude
    * `BETTER_AUTH_SECRET` -- Authentication secret
    * `BAP_CLOUD_API_BASE_URL` -- Bap Cloud base URL for delegated login
    * `BAP_CLOUD_INSTANCE_API_KEY` -- Shared control-plane instance key
  </Step>

  <Step title="Set up the database">
    Push the schema to your database:

    ```bash theme={null}
    bun run --cwd packages/db db:push
    ```

    Optionally seed with initial data:

    ```bash theme={null}
    bun run --cwd packages/db db:seed
    ```
  </Step>

  <Step title="Start the app">
    ```bash theme={null}
    bun dev
    ```

    This starts the web app, worker, and WS runtime from the monorepo root.
    The web app will be available at `http://localhost:3000`.
  </Step>
</Steps>

## Docker Compose (all-in-one)

For a fully containerized setup backed by published GHCR images (app + worker + DB + Redis + MinIO),
use the bundled compose file at `docker/compose/selfhost.yml`:

```bash theme={null}
cp .env.selfhost.example .env.selfhost
```

Fill in at least:

* `APP_URL`
* `BETTER_AUTH_SECRET`
* `ENCRYPTION_KEY`
* `BAP_SERVER_SECRET`
* `BAP_CLOUD_API_BASE_URL`
* `BAP_CLOUD_INSTANCE_API_KEY`
* `OPENAI_API_KEY`
* `ANTHROPIC_API_KEY`

Optionally pin the image tags in `/.env.selfhost`:

```env theme={null}
BAP_APP_IMAGE=ghcr.io/baptistecolle/bap-web:main
BAP_WORKER_IMAGE=ghcr.io/baptistecolle/bap-worker:main
```

Then pull, migrate, and start:

```bash theme={null}
docker compose -f docker/compose/selfhost.yml --env-file .env.selfhost pull
docker compose -f docker/compose/selfhost.yml --env-file .env.selfhost run --rm migrate
docker compose -f docker/compose/selfhost.yml --env-file .env.selfhost up -d
```

Then open `http://localhost:8114`.

Self-hosted end-user login is delegated to Bap Cloud. Configure the same
`BAP_CLOUD_INSTANCE_API_KEY` on the cloud deployment and on each self-hosted deployment
that should trust it.

* Set `E2B_API_KEY` and `E2B_DAYTONA_SANDBOX_NAME` to use E2B cloud sandboxes.
* Or set `DAYTONA_API_KEY` (plus optional `DAYTONA_API_URL` / `DAYTONA_SERVER_URL` / `DAYTONA_TARGET`) to use Daytona sandboxes.
* Or set `SANDBOX_DEFAULT=docker` to use local Docker-based sandboxes.
* Published images also get a daily `YYYYMMDD-N` tag such as `20260310-1`.
* Use a `sha-...` tag instead of `main` if you want to test a specific published build.
* The published `app` image does not include custom browser-side `VITE_POSTHOG_*` values; build `docker/images/web/Dockerfile` yourself if you need them.

## Background worker

Bap uses BullMQ for generation execution and background jobs. Chat and coworker runs are
executed by the worker, so start it in a separate terminal:

```bash theme={null}
bun start:worker
```

This command loads `/.env` so the worker uses the same local environment as `bun dev`.

## WebSocket server

The WebSocket server still runs separately from the web app:

```bash theme={null}
bun start:ws
```

This command also loads `/.env`.

## Useful commands

| Command                               | Description                                   |
| ------------------------------------- | --------------------------------------------- |
| `bun dev`                             | Start the web app, worker, and WS runtime     |
| `bun dev:web`                         | Start only the web app                        |
| `bun dev:worker`                      | Start only the worker                         |
| `bun dev:ws`                          | Start only the WS runtime                     |
| `bun build`                           | Production build                              |
| `bun check`                           | Run workspace checks                          |
| `bun test`                            | Run workspace tests                           |
| `bun start:worker`                    | Start the background job worker using `/.env` |
| `bun start:ws`                        | Start the WebSocket server using `/.env`      |
| `bun run --cwd packages/db db:push`   | Push schema changes to the database           |
| `bun run --cwd packages/db db:studio` | Open Drizzle Studio (database browser)        |
| `bun run --cwd packages/db db:seed`   | Seed the database                             |

## Tech stack

| Layer    | Technology                               |
| -------- | ---------------------------------------- |
| Web      | TanStack Start, React 19, Tailwind CSS 4 |
| API      | ORPC, Better Auth                        |
| Database | PostgreSQL, Drizzle ORM                  |
| AI       | Anthropic Claude, OpenAI, Google Gemini  |
| Queue    | BullMQ, Redis                            |
| Storage  | S3 / MinIO                               |
| Sandbox  | E2B, Daytona, Docker                     |