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

# Docker

> Understand the modular Docker architecture for development and production deployments

The Launchpad uses a modular Docker Compose architecture that lets you include or exclude services based on your needs. All services run on a shared bridge network for seamless communication.

## Compose File Structure

The Docker setup is split into four compose files:

| File                           | Purpose                                     |
| ------------------------------ | ------------------------------------------- |
| `docker-compose.yml`           | Main orchestrator that includes other files |
| `docker-compose.launchpad.yml` | Core application services                   |
| `docker-compose.supabase.yml`  | Supabase backend services                   |
| `docker-compose.caddy.yml`     | Reverse proxy with automatic HTTPS          |

### Main Compose File

The `docker-compose.yml` file controls which services to include. By default only the core Launchpad stack is on; Supabase and Caddy are commented out. Uncomment Supabase when you need Studio/Auth/Realtime/Storage, and uncomment Caddy when you need HTTPS in front of the API (typical for VPS deployments):

```yaml theme={null}
include:
  - path: ./docker-compose.launchpad.yml
  # - path: ./docker-compose.supabase.yml  # Uncomment to enable Supabase services
#  - path: ./docker-compose.caddy.yml      # Uncomment to enable Caddy/HTTPS

networks:
  default:
    driver: bridge
    external: true
    name: "${PROJECT_NAME}-network"
```

## Core Application Services

The `docker-compose.launchpad.yml` file contains the essential application services:

| Service            | Image                        | Port | Purpose                    |
| ------------------ | ---------------------------- | ---- | -------------------------- |
| **api**            | Custom (Dockerfile.api)      | 8080 | FastAPI application server |
| **celery\_worker** | Custom (Dockerfile.celery)   | -    | Async task processing      |
| **redis**          | redis:latest                 | 6379 | Message broker & cache     |
| **db**             | supabase/postgres:15.8.1.085 | 5432 | PostgreSQL database        |

The API and Celery services mount the host `app/` into `/workspace/app` for live code reloading during development. The package is installed editable inside the image, so edits in the host `app/launchpad/` tree take effect without a rebuild.

## Supabase Services

The `docker-compose.supabase.yml` file is opt-in and provides the full Supabase stack:

| Service       | Image                  | Purpose                        |
| ------------- | ---------------------- | ------------------------------ |
| **studio**    | supabase/studio        | Dashboard UI                   |
| **kong**      | kong:2.8.1             | API gateway (ports 8000, 8443) |
| **auth**      | supabase/gotrue        | Authentication service         |
| **rest**      | postgrest/postgrest    | Auto-generated REST API        |
| **realtime**  | supabase/realtime      | WebSocket subscriptions        |
| **storage**   | supabase/storage-api   | File storage                   |
| **imgproxy**  | darthsim/imgproxy      | Image transformations          |
| **meta**      | supabase/postgres-meta | Schema introspection           |
| **functions** | supabase/edge-runtime  | Deno edge functions            |
| **analytics** | supabase/logflare      | Log aggregation                |
| **vector**    | timberio/vector        | Log collection                 |
| **supavisor** | supabase/supavisor     | Connection pooling             |

<Info>
  When Supabase is enabled, access the Studio dashboard at `http://localhost:8000` with credentials from `docker/.env`.
</Info>

## Caddy Reverse Proxy

The `docker-compose.caddy.yml` file provides:

* Automatic HTTPS certificate management
* Reverse proxy to application services
* HTTP/2 support
* Ports: 80 (HTTP), 443 (HTTPS), 2019 (admin API)

## Including and Excluding Services

### Option 1: Edit docker-compose.yml

Uncomment the services you need:

```yaml theme={null}
include:
  - path: ./docker-compose.launchpad.yml      # Always include
  # - path: ./docker-compose.supabase.yml     # Enable Supabase
  # - path: ./docker-compose.caddy.yml        # Enable Caddy
```

### Option 2: Use CLI flags

Specify which compose files to use:

```bash theme={null}
# Default core stack
docker compose -f docker-compose.launchpad.yml up

# Core + Supabase
docker compose -f docker-compose.launchpad.yml \
               -f docker-compose.supabase.yml up

# Whatever is enabled in docker-compose.yml
docker compose up
```

## Management Scripts

The `docker/` directory includes helper scripts:

### start.sh

Creates the network if needed and starts all services:

```bash theme={null}
cd docker && ./start.sh
```

### stop.sh

Stops all running containers:

```bash theme={null}
cd docker && ./stop.sh
```

### logs.sh

Interactive log viewer with service selection:

```bash theme={null}
cd docker && ./logs.sh
```

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                    Caddy (optional)                     │
│                   :80, :443, :2019                      │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                 Kong API Gateway                        │
│                  :8000, :8443                           │
└───────┬─────────────┬─────────────┬─────────────────────┘
        │             │             │
┌───────▼───────┐ ┌───▼───────┐ ┌───▼───────────────────┐
│  Auth/GoTrue  │ │ PostgREST │ │ Storage / Realtime /  │
│    :9999      │ │   :3000   │ │ Functions / etc.      │
└───────┬───────┘ └─────┬─────┘ └───────────┬───────────┘
        │               │                   │
┌───────▼───────────────▼───────────────────▼─────────────┐
│              PostgreSQL Database                        │
│              supabase/postgres:15.8.1.085              │
│              :5432 (direct) / :6543 (pooled)           │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│               Application Services                      │
│  ┌─────────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │ FastAPI (:8080) │  │ Celery Worker│  │   Redis   │  │
│  │ /workspace/app  │  │  async tasks │  │   :6379   │  │
│  └─────────────────┘  └──────────────┘  └───────────┘  │
└─────────────────────────────────────────────────────────┘

All services connected via: ${PROJECT_NAME}-network
```

## Environment Variables

The Launchpad has two `.env` files because local Python runs and Docker Compose read configuration in different ways.

| File                    | Used by                                                                                                       | Purpose                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `.env` at the repo root | Local Python commands, including playground scripts, unit tests, notebooks, and one-off scripts run with `uv` | Keeps local development credentials close to the Python process that loads them with `python-dotenv`                                   |
| `docker/.env`           | Docker Compose, containers, the database, and optional Supabase services                                      | Feeds Compose interpolation, container environment variables, database credentials, ports, JWT/secrets, and Supabase-specific settings |

`docker/.env` is intentionally much larger than the root `.env` because self-hosted Supabase requires many variables for Auth, Realtime, Storage, Studio, Kong, analytics, and related services. Those values stay in `docker/.env` even when Supabase is commented out by default, so opting in later is a compose-file change rather than a config migration.

For local Python runs that connect to the Docker database through `localhost`, the root `.env` database user depends on whether Supabase is enabled. Use `DATABASE_USER=postgres` with the default Launchpad-only stack. When `docker-compose.supabase.yml` is included, port `5432` is served by Supavisor, so use `DATABASE_USER=postgres.<POOLER_TENANT_ID>`, for example `postgres.launchpad`.

Key environment variables in `docker/.env`:

| Category          | Variables                                                         |
| ----------------- | ----------------------------------------------------------------- |
| **Project**       | `PROJECT_NAME`                                                    |
| **Database**      | `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_PORT`               |
| **JWT**           | `JWT_SECRET`, `JWT_EXPIRY`, `ANON_KEY`, `SERVICE_ROLE_KEY`        |
| **LLM Providers** | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `MISTRAL_API_KEY`, etc.    |
| **Langfuse**      | `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL` |

Copy `docker/.env.example` to `docker/.env` and configure your values before starting.