> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Docker Compose Reference
> Annotated walkthrough of every service, port, and profile in the shipped docker-compose.yml
The `docker-compose.yml` at the root of the [cognee repository](https://github.com/topoteretes/cognee) defines seven services. Only two of them start by default — everything else is gated behind a [Compose profile](https://docs.docker.com/compose/how-tos/profiles/). This page explains what each service is for, so you can decide which ones you actually need.
For setup instructions and common stacks, see [Docker Deployment](/how-to-guides/cognee-sdk/deployment/docker).
## Service overview
| Service | Profile | Host ports | Required? | Purpose |
| -------------- | ---------- | -------------- | --------- | ----------------------------------------------------------- |
| `cognee` | *(none)* | `8000`, `5678` | **Yes** | The Cognee REST API server |
| `redisinsight` | *(none)* | `5540` | No | Redis browser GUI (developer convenience) |
| `cognee-mcp` | `mcp` | `8001`, `5679` | No | [MCP server](/cognee-mcp/mcp-overview) for IDE integrations |
| `frontend` | `ui` | `3000` | No | Experimental [web UI](/cognee-cloud/local-ui) |
| `postgres` | `postgres` | `5432` | No | PostgreSQL + pgvector |
| `neo4j` | `neo4j` | `7474`, `7687` | No | Neo4j graph database |
| `redis` | `redis` | `6379` | No | Redis, for the session cache |
A service with no `profiles:` key starts whenever you run a bare `docker compose up`. That means `redisinsight` comes up alongside `cognee` even if you never configure Redis. Run `docker compose up cognee` to start only the API server.
## Services in detail
Built from the repository `Dockerfile` and started by `docker compose up --build cognee`. This is the only service you need for a working deployment; the default [relational](/setup-configuration/relational-databases), [vector](/setup-configuration/vector-stores), and [graph](/setup-configuration/graph-stores) stores are all embedded and run inside this container.
* `8000` — the FastAPI app (`http://localhost:8000/docs` for interactive docs).
* `5678` — `debugpy`, used only when `DEBUG=true` and `ENV` is `dev` or `local`.
* Mounts `./cognee` from the host for **dev reload only**, and `.env` read-only (`:ro`), so config changes need only a restart, not a rebuild.
* Persists memory in the `cognee_system` and `cognee_data` named volumes, mounted at `/cognee-storage/system` and `/cognee-storage/data` — the image's baked-in `SYSTEM_ROOT_DIRECTORY` / `DATA_ROOT_DIRECTORY`. These are the same volumes `cognee-mcp` mounts, so both services read and write one memory store.
* Runs as the non-root user `cognee` (uid/gid 1000), matching `cognee-mcp` so the shared volumes have no ownership conflicts.
* Passes `DB_PROVIDER`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USERNAME`, and `DB_PASSWORD` through from your environment or `.env`, defaulting to embedded SQLite; the `DB_HOST`/`DB_PORT` defaults (`host.docker.internal:5432`) only apply once you switch `DB_PROVIDER` to `postgres`. For `--profile postgres`, set `DB_PROVIDER=postgres` and `DB_HOST=postgres`.
* Has a `healthcheck` that polls `/health` every 30s after a 40s grace period.
Enabled with `--profile mcp`. Exposes Cognee's tools over the Model Context Protocol so Cursor, Claude Desktop, VS Code, and similar clients can call them.
* Runs with `TRANSPORT_MODE=sse`, so clients connect to `http://localhost:8001/sse`.
* Host ports (`8001`, `5679`) differ from the `cognee` service, but inside the container it still listens on `8000`/`5678` — that's why both can run at once.
* Started with `--no-migration`, so it does not run Alembic migrations. Let the `cognee` service own the schema, and point both at the same database via the `DB_*` variables.
* Mounts the **same** `cognee_system` / `cognee_data` volumes as the `cognee` service, at `/cognee-storage/system` and `/cognee-storage/data`. Sharing one memory store between the API and the MCP server is the point of running both — the image runs as the same non-root user (uid/gid 1000) as `cognee`, so neither container can create files the other cannot write.
* Has a `healthcheck` that polls `/health` on the container's port `8000` every 30s after a 40s grace period. It probes with `python -c "import urllib.request..."` rather than `curl`, which the python-slim MCP runtime image does not ship.
* Optional. Skip it if you only use the REST API or the Python SDK.
Enabled with `--profile ui`. A Next.js app built from `./cognee-frontend` that talks to the API at `NEXT_PUBLIC_BACKEND_API_URL` (default `http://localhost:8000`).
Optional and explicitly a work in progress — it supports the minimum feature set needed to be functional. For a richer experience, use the `mcp` profile with your IDE or [Cognee Cloud](/cognee-cloud/overview).
Enabled with `--profile postgres`. Uses the `pgvector/pgvector:pg17` image, so the same container can serve as the [relational database](/setup-configuration/relational-databases) (`DB_PROVIDER=postgres`) and the [vector store](/setup-configuration/vector-stores) (`VECTOR_DB_PROVIDER=pgvector`).
Ships with `cognee` / `cognee` / `cognee_db` as user, password, and database name. Optional — Cognee defaults to SQLite and LanceDB, which need no service at all.
* Mounts the `postgres_data` named volume at `/var/lib/postgresql/data`, so the database survives `docker compose up --force-recreate postgres` and `docker compose down`. Deleting the volume (`docker compose down -v`) still discards it. See [Data Persistence and Host Files](/how-to-guides/cognee-sdk/deployment/docker#additional-information).
* Has a `healthcheck` that runs `pg_isready -U cognee -d cognee_db` every 10s, 5 retries, after a 10s grace period.
No service in the shipped file declares `depends_on`, so the healthcheck only reports state — it does not hold `cognee` back until Postgres accepts connections. Add a `depends_on: condition: service_healthy` guard yourself if startup ordering matters; see [PostgreSQL Connection Refused](/how-to-guides/cognee-sdk/deployment/docker#postgresql-connection-refused).
Enabled with `--profile neo4j`. Pinned to `neo4j:5.26` for compatibility with the Neo4j Python driver, with the APOC and Graph Data Science plugins preloaded.
* `7474` — Neo4j Browser.
* `7687` — Bolt protocol; set `GRAPH_DATABASE_URL=bolt://neo4j:7687`.
* Default credentials are `neo4j` / `pleaseletmein`.
Optional. Use it instead of the embedded file-based graph store when the graph should live in an external database rather than in files owned by the Cognee container. No data volume is mounted, so add one for durability.
Enabled with `--profile redis`. Runs `redis:7-alpine` with append-only persistence into the `redis_data` volume.
Only needed when you set `CACHE_BACKEND=redis` for [sessions and caching](/core-concepts/sessions-and-caching); the default cache backend is SQLite. Point Cognee at it with `CACHE_HOST=redis` and `CACHE_PORT=6379`.
This service backs the *session cache*. Using Redis as a [vector store](/setup-configuration/community-maintained/redis) is a separate, community-maintained adapter that needs the Redis Search module.
[RedisInsight](https://redis.io/insight/) is Redis' official browser-based inspector. It is a **developer convenience only** — Cognee never talks to it, and nothing breaks if you remove it.
Open `http://localhost:5540` and connect to host `redis`, port `6379` to inspect cached sessions. Because it has no profile, it starts with a bare `docker compose up`; name the services you want (`docker compose up cognee`) or delete the block if you don't need it.
## Shared building blocks
All services join the user-defined bridge network `cognee-network`. Inside it, containers reach each other by **service name** — that is why `DB_HOST=postgres` and `GRAPH_DATABASE_URL=bolt://neo4j:7687` work, while `localhost` would resolve to the container itself.
The `cognee` and `cognee-mcp` services map `host.docker.internal` to `host-gateway`:
```yaml theme={null}
extra_hosts:
- "host.docker.internal:host-gateway"
```
This lets a container reach services running directly on your machine — an Ollama server, or a Postgres instance you started outside Compose. Use `host.docker.internal` in place of `localhost` for those, for example `LLM_ENDPOINT=http://host.docker.internal:11434/v1`.
```yaml theme={null}
deploy:
resources:
limits:
cpus: "4.0"
memory: 8GB
```
Docker Compose v2 applies these as hard CPU and memory caps: `4.0` CPUs / 8 GB for `cognee`, `2.0` CPUs / 4 GB for `cognee-mcp`. Lower them if your machine has less headroom; raise them if large ingestion runs are being OOM-killed. On Docker Desktop the limits cannot exceed what the VM itself is allocated.
Profiles are additive — repeat the flag to start several optional services together:
```bash theme={null}
docker compose --profile postgres --profile neo4j up --build
```
You can also set them once for the shell session:
```bash theme={null}
export COMPOSE_PROFILES=postgres,neo4j
docker compose up --build
```
Join our community for Docker deployment support.