Skip to main content
The docker-compose.yml at the root of the cognee repository defines seven services. Only two of them start by default — everything else is gated behind a Compose profile. 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.

​
Service overview

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, vector, and graph 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 and .env from the host, so config changes need only a restart, not a rebuild.
  • 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.
  • 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.
Enabled with --profile postgres. Uses the pgvector/pgvector:pg17 image, so the same container can serve as the relational database (DB_PROVIDER=postgres) and the vector store (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.
The postgres_data volume is declared but the mount is commented out in the shipped file, so data is lost when the container is removed. See Data Persistence and Host Files.
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 you need concurrent access from multiple processes. 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; 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 is a separate, community-maintained adapter that needs the Redis Search module.
RedisInsight 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:
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.
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:
You can also set them once for the shell session:

Need help?

Join our community for Docker deployment support.