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

# Installation Guide

> Step-by-step installation for GenAI Launchpad

<Info>
  Before you begin, ensure you have completed the system requirements setup.
</Info>

<Tabs>
  <Tab title="macOS & Linux">
    <Steps>
      <Step title="Clone the repository">
        Open your terminal and navigate to your desired project directory:

        ```bash theme={null}
        cd desired/project/path
        ```

        Clone the GenAI Launchpad repository:

        ```bash theme={null}
        git clone git@github.com:datalumina/genai-launchpad.git
        ```
      </Step>

      <Step title="Configure environment variables">
        Navigate to the project directory:

        ```bash theme={null}
        cd genai-launchpad
        ```

        Copy the example environment files:

        ```bash theme={null}
        cp .env.example .env && cp docker/.env.example docker/.env
        ```

        These files serve different runtimes:

        | File          | Used by                                                                                               | What belongs here                                                                                                                            |
        | ------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
        | `.env`        | Local Python runs from your machine, such as `uv run playground/...`, unit tests, and one-off scripts | LLM provider keys, Langfuse keys, and local app settings loaded by `python-dotenv`                                                           |
        | `docker/.env` | Docker Compose, the containerized Launchpad stack, the database, and optional Supabase services       | Compose project settings, database credentials, container ports, JWT/secrets, Docker-side provider keys, and optional Supabase configuration |

        <Warning>
          `docker/.env` is much larger mostly because self-hosted Supabase needs many settings, even though Supabase services are excluded by default.
        </Warning>
      </Step>

      <Step title="Start Docker containers">
        Navigate to the Docker directory and start the containers:

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

        This command will:

        * Build all Docker containers
        * Start all services via Docker Compose

        Verify the containers are running:

        ```bash theme={null}
        docker ps
        ```
      </Step>

      <Step title="Set up Python environment">
        Return to the project root and sync the environment:

        ```bash theme={null}
        cd ../
        uv sync
        ```

        `uv sync` creates and manages the `.venv`, installs the pinned Python version if needed, and installs the Launchpad package in editable mode.
      </Step>

      <Step title="Run database migrations">
        Navigate to the package directory where `alembic.ini` and the migration scripts live:

        ```bash theme={null}
        cd app/launchpad
        ```

        Create a new migration (you'll be prompted for a description):

        ```bash theme={null}
        ./makemigration.sh
        ```

        <Warning>
          When prompted, enter a descriptive message like "init db" for your first migration.
        </Warning>

        Apply the migration:

        ```bash theme={null}
        ./migrate.sh
        ```
      </Step>

      <Step title="Optional: enable Supabase services">
        Supabase Studio, Auth, Realtime, Storage, and the Supabase gateway are excluded by default. To enable them, uncomment `docker-compose.supabase.yml` in `docker/docker-compose.yml`, then restart the Docker stack.

        If you run Python locally against the Docker database, update the root `.env` database user from `postgres` to `postgres.<POOLER_TENANT_ID>`, for example `postgres.launchpad` with the default `docker/.env` settings. Supavisor requires the tenant-qualified username.

        When enabled, Studio is available at [http://localhost:8000](http://localhost:8000) with the dashboard credentials from `docker/.env`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows">
    <Info>
      Windows users should use either Git Bash or Ubuntu WSL (WSL preferred) for the best experience.
    </Info>

    <Steps>
      <Step title="Clone the repository">
        Open Git Bash or Ubuntu WSL and navigate to your desired project directory:

        ```bash theme={null}
        cd desired/project/path
        ```

        Clone the GenAI Launchpad repository:

        ```bash theme={null}
        git clone git@github.com:datalumina/genai-launchpad.git
        ```
      </Step>

      <Step title="Configure environment variables">
        Navigate to the project directory:

        ```bash theme={null}
        cd genai-launchpad
        ```

        Copy the example environment files:

        ```bash theme={null}
        cp .env.example .env && cp docker/.env.example docker/.env
        ```

        These files serve different runtimes:

        | File          | Used by                                                                                               | What belongs here                                                                                                                            |
        | ------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
        | `.env`        | Local Python runs from your machine, such as `uv run playground/...`, unit tests, and one-off scripts | LLM provider keys, Langfuse keys, and local app settings loaded by `python-dotenv`                                                           |
        | `docker/.env` | Docker Compose, the containerized Launchpad stack, the database, and optional Supabase services       | Compose project settings, database credentials, container ports, JWT/secrets, Docker-side provider keys, and optional Supabase configuration |

        <Warning>
          `docker/.env` is much larger mostly because self-hosted Supabase needs many settings, even though Supabase services are excluded by default.
        </Warning>
      </Step>

      <Step title="Start Docker containers">
        Navigate to the Docker directory and start the containers:

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

        This command will:

        * Build all Docker containers
        * Start all services via Docker Compose

        Verify the containers are running:

        ```bash theme={null}
        docker ps
        ```
      </Step>

      <Step title="Set up Python environment">
        Return to the project root and sync the environment:

        ```bash theme={null}
        cd ../
        uv sync
        ```

        `uv sync` creates and manages the `.venv`, installs the pinned Python version if needed, and installs the Launchpad package in editable mode.
      </Step>

      <Step title="Run database migrations">
        Navigate to the package directory where `alembic.ini` and the migration scripts live:

        ```bash theme={null}
        cd app/launchpad
        ```

        Create a new migration (you'll be prompted for a description):

        ```bash theme={null}
        ./makemigration.sh
        ```

        <Warning>
          When prompted, enter a descriptive message like "init db" for your first migration.
        </Warning>

        Apply the migration:

        ```bash theme={null}
        ./migrate.sh
        ```
      </Step>

      <Step title="Optional: enable Supabase services">
        Supabase Studio, Auth, Realtime, Storage, and the Supabase gateway are excluded by default. To enable them, uncomment `docker-compose.supabase.yml` in `docker/docker-compose.yml`, then restart the Docker stack.

        If you run Python locally against the Docker database, update the root `.env` database user from `postgres` to `postgres.<POOLER_TENANT_ID>`, for example `postgres.launchpad` with the default `docker/.env` settings. Supavisor requires the tenant-qualified username.

        When enabled, Studio is available at [http://localhost:8000](http://localhost:8000) with the dashboard credentials from `docker/.env`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Exercise workflows from the playground

The `playground/` directory contains one script per reference workflow. Each script loads a matching JSON fixture from the workflow's `request_examples/` folder, runs the workflow in-process, and prints the final `TaskContext`. They are the fastest way to iterate on a workflow without running the full API + Celery stack.

| Script                           | Workflow                   | What it does                                                                                          |
| -------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `playground/quickstart.py`       | `CustomerCareWorkflow`     | Runs a customer-care ticket end-to-end (concurrent analysis → routing → reply).                       |
| `playground/nested_workflow.py`  | `NestedWorkflow`           | Runs a parent workflow that delegates reply drafting to a child workflow with the same `TaskContext`. |
| `playground/streaming.py`        | `ExampleStreamingWorkflow` | Iterates `run_stream_async` and prints each streamed chunk.                                           |
| `playground/langfuse_tracing.py` | `LangfuseTracingWorkflow`  | Runs the moderation pipeline; set `LANGFUSE_*` env vars to capture traces.                            |
| `playground/pgvector_rag.py`     | `RagExampleWorkflow`       | Runs retrieval + generation against the pgvector collection.                                          |

Run any of them with `uv`:

```bash theme={null}
uv run playground/quickstart.py
```