Skip to main content
The docker-compose.yml at the root of the cognee repository defines eight 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 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 run from the published cognee/cognee-ui image — the same image CI builds, so this profile works from a bare docker-compose.yml with no checkout of cognee-frontend.
  • Image tag comes from COGNEE_UI_TAG, defaulting to latest.
  • Waits for the cognee service to report healthy (depends_on: condition: service_healthy) before starting.
  • Passes COGNEE_BACKEND_URL through from your environment, defaulting to empty. It is read at run time, not baked in at build time, which is what lets one published image point at any backend. Empty means the browser derives the backend host from the address the UI was loaded from, on port 8000 — right for the default localhost setup. Because the browser calls the backend directly, a value you do set must be the address as seen from the browser, never the cognee service name.
  • The image’s entrypoint rejects a COGNEE_BACKEND_URL that is not an absolute http(s) URL and exits rather than starting; see Cognee + Web UI.
  • Has a baked-in healthcheck that fetches /api/runtime-config every 30s after a 20s grace period — the cheapest endpoint that proves both that the server is up and that the backend URL resolved.
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 ui-dev. Builds the dev target of cognee-frontend/Dockerfile — a hot-reloading next dev server — and bind-mounts ./cognee-frontend/src and ./cognee-frontend/public, so source edits are picked up without a rebuild. Never published; it exists for frontend work.Takes the same COGNEE_BACKEND_URL as frontend and publishes the same host port 3000, so the two profiles are alternatives, not additions. Unlike frontend, it declares no depends_on, so it starts without waiting for the API.
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.
  • 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.
  • Has a healthcheck that runs pg_isready -U cognee -d cognee_db every 10s, 5 retries, after a 10s grace period.
Nothing in the shipped file declares depends_on on postgres — only frontend uses one, to wait on cognee — so this 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.
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; 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.
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.