> ## 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 self-hosted deployment.

> [!NOTE]
>
> **Observatory availability.** In FlowX.AI 6.0, Observatory runs on environments operated by FlowX. It isn't included in client deployments in this release.

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 |
| `observatory-docs` | 4903 | Bundled docs site |

> [!NOTE]
>
> 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.

***

## Steps

**1. Clone the repo**

```bash theme={"dark"}
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={"dark"}
git submodule update --init --recursive
```

**2. Create the network**

The platform expects an external Docker network shared with other FlowX services:

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

**3. Configure the .env file**

Copy the example and edit the placeholders:

```bash theme={"dark"}
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](https://docs.flowx.ai/6.x/observatory/setup/environment-variables.md) for the full table.

**4. Bring up the stack**

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

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

> [!TIP]
>
> `docker compose ps` shows all services in state `Up` or `healthy`.

**5. 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.

**6. Confirm the API**

```bash theme={"dark"}
curl http://localhost:8091/health
```

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

***

## Rebuilding after code changes

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

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

> [!WARNING]
>
> `docker compose restart` does not rebuild images. Always use `up -d --build` after touching service code.

***

## 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={"dark"}
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

> [accordion] Containers start but the UI shows 503
>
> 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] Postgres fails to start with 'database does not exist'
>
> 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] The SDK can't reach the API from outside Docker
>
> `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).

***

## Related resources

> [card] [Environment variables](https://docs.flowx.ai/6.x/observatory/setup/environment-variables.md)
>
> Full reference for every env var the platform reads.

> [card] [Getting started](https://docs.flowx.ai/6.x/observatory/getting-started.md)
>
> Once the platform is up, instrument your first agent.


## Related topics

- [Observatory](https://docs.flowx.ai/6.x/observatory/overview.md)
- [Environment variables](https://docs.flowx.ai/6.x/observatory/setup/environment-variables.md)
- [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](https://docs.flowx.ai/6.x/setup-guides/migrate-to-flowx-ai-helm-chart.md)
- [License service setup](https://docs.flowx.ai/6.x/setup-guides/license-engine-setup.md)
- [Organization Manager setup](https://docs.flowx.ai/6.x/setup-guides/organization-manager-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.