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

# Self-hosted setup

> Stand up Observatory locally with Docker Compose for development, evaluation, or on-premise deployment.

Observatory ships as a set of containers you can bring up together. This guide is the fastest path from zero to a running platform you can point the SDK at.

***

## Prerequisites

* Docker 24+ and Docker Compose v2
* 8 GB RAM available for containers
* 20 GB disk available for PostgreSQL data
* Network access to the upstream LLM providers you intend to use

The default Compose stack includes:

| Service                | Port | Purpose                                                        |
| ---------------------- | ---- | -------------------------------------------------------------- |
| `observatory-api`      | 8091 | FastAPI backend                                                |
| `observatory-web`      | 4900 | Angular dashboard                                              |
| `observatory-platform` | 8092 | Platform service (organizations, RBAC, Kubernetes integration) |
| `observatory-db`       | 5432 | PostgreSQL with `pgvector`                                     |
| `observatory-docs`     | 4903 | Bundled docs site                                              |

<Info>
  Observatory authenticates against an **external** FlowX identity provider (Keycloak) — it is not bundled in the Compose stack. Point `SECURITY_OAUTH2_*` / `KEYCLOAK_*` at your auth server.
</Info>

***

## Steps

<Steps>
  <Step title="Clone the repo">
    ```bash theme={"system"}
    git clone --recurse-submodules git@github.com:flowx-ai/observatory2.0.git
    cd observatory2.0
    ```

    The submodules carry the API, web, platform, and SDK source. If you forgot `--recurse-submodules`, run:

    ```bash theme={"system"}
    git submodule update --init --recursive
    ```
  </Step>

  <Step title="Create the network">
    The platform expects an external Docker network shared with other FlowX services:

    ```bash theme={"system"}
    docker network create ai-services_node-network 2>/dev/null || true
    ```
  </Step>

  <Step title="Configure the .env file">
    Copy the example and edit the placeholders:

    ```bash theme={"system"}
    cp observatory-api/env.example observatory-api/.env
    ```

    At minimum set `OPENAI_API_KEY` (or your provider equivalent), the `SECURITY_OAUTH2_*` values for your identity provider, and any custom LLM endpoints. See [Environment variables](./environment-variables) for the full table.
  </Step>

  <Step title="Bring up the stack">
    ```bash theme={"system"}
    docker compose up -d --build
    ```

    First start takes a few minutes — the databases initialise and schemas are created.

    <Check>
      `docker compose ps` shows all services in state `Up` or `healthy`.
    </Check>
  </Step>

  <Step title="Confirm the web UI">
    Open [http://localhost:4900](http://localhost:4900). You should see the login page. Sign in with credentials from your FlowX identity provider.
  </Step>

  <Step title="Confirm the API">
    ```bash theme={"system"}
    curl http://localhost:8091/health
    ```

    A `{"status": "ok"}` response means the API is reachable. The `/docs` endpoint serves the OpenAPI explorer.
  </Step>
</Steps>

***

## Rebuilding after code changes

When you edit source code in a submodule, always rebuild — restarting alone won't pick up the changes:

```bash theme={"system"}
docker compose up -d --build
```

<Warning>
  `docker compose restart` does not rebuild images. Always use `up -d --build` after touching service code.
</Warning>

***

## Persistence

The Compose stack persists:

* `pgdata` volume — all telemetry, evidence, runs
* `hf_hub` volume — cached model files

Both survive `docker compose down`. To wipe the platform back to factory state:

```bash theme={"system"}
docker compose down -v
```

***

## Production deployment

The Compose stack is for development and evaluation. For production, see the Kubernetes manifests under `deployment/` and the deployment guide in the repo. Notable production-only concerns:

* Configure persistent volumes for the database
* Set up TLS at the ingress layer
* Point auth at your production identity provider

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Containers start but the UI shows 503" icon="circle-question">
    Most often a missing port name in the service definition. Confirm `observatory-api` is reachable on port 8091 from the `observatory-web` container with `docker compose exec observatory-web curl http://observatory-api:8091/health`.
  </Accordion>

  <Accordion title="Postgres fails to start with 'database does not exist'" icon="circle-question">
    The init script in `init_dbs/multiple-databases.sh` creates the companion databases on first start. If it didn't run, your existing pgdata volume is from an older build. Wipe and start over: `docker compose down -v && docker compose up -d --build`.
  </Accordion>

  <Accordion title="The SDK can't reach the API from outside Docker" icon="circle-question">
    `FLOWX_OBSERVATORY_API_URL` must be `http://localhost:8091` for a host-machine app, not `http://observatory-api:8091` (which only resolves inside the Docker network).
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Environment variables" icon="list" href="./environment-variables">
    Full reference for every env var the platform reads.
  </Card>

  <Card title="Getting started" icon="rocket" href="../getting-started">
    Once the platform is up, instrument your first agent.
  </Card>
</CardGroup>