Docker Deployment - Cognee Documentation

Deploy Cognee locally or on a server with Docker Compose. The included docker-compose.yml uses profiles so you can start only the services you need.

Prerequisites

Docker and Docker Compose v2+
Git

Quick Start

git clone https://github.com/topoteretes/cognee.git
cd cognee
cp .env.template .env

Edit .env and set your LLM API key:

LLM_API_KEY="your_api_key"

Then start the Cognee API server (no profile needed):

docker compose up --build cognee

The API will be available at http://localhost:8000. Interactive docs at http://localhost:8000/docs.

Service Profiles

Each optional service is gated behind a profile. Use --profile to activate one or more:

Profile	Service	Port(s)	Purpose
(none)	`cognee`	`8000`, `5678`	Core API server
`mcp`	`cognee-mcp`	`8000`, `5678`	MCP server for IDE integrations
`ui`	`frontend`	`3000`	Experimental web UI
`neo4j`	`neo4j`	`7474`, `7687`	Neo4j graph database
`chromadb`	`chromadb`	`3002`	ChromaDB vector database
`postgres`	`postgres`	`5432`	PostgreSQL + pgvector
`redis`	`redis`	`6379`	Redis caching

Data Persistence

The compose file mounts your local cognee/ source directory and .env file into the container. Named volumes persist database data between restarts:

Service	Volume
`postgres`	`postgres_data`
`chromadb`	`.chromadb_data/` (local dir)
`redis`	`redis_data`

To ingest files from your host machine, uncomment and update the volume in docker-compose.yml.

# - /path/to/your/data:/data

Environment Variables

The cognee container reads configuration from .env at startup. Key variables:

Variable	Default	Description
`LLM_API_KEY`	(required)	API key for your LLM provider
`LLM_MODEL`	`openai/gpt-4o-mini`	LLM model to use
`DB_PROVIDER`	`sqlite`	Relational DB: `sqlite` or `postgres`
`GRAPH_DATABASE_PROVIDER`	`kuzu`	Graph DB: `kuzu`, `neo4j`, etc.
`VECTOR_DB_PROVIDER`	`lancedb`	Vector DB: `lancedb`, `chromadb`, `pgvector`, etc.
`CORS_ALLOWED_ORIGINS`	`*`	Restrict to specific domains in production
`REQUIRE_AUTHENTICATION`	`false`	Enable JWT auth for the API
`COGNEE_SKIP_CONNECTION_TEST`	`false`	Skip LLM/embedding connectivity checks on startup. Accepts `true`, `1`, or `yes`.
`chunk_size`	`1500`	Max tokens per chunk during cognify (see Chunkers)
`chunk_overlap`	`10`	Overlap between chunks in words (only affects `LangchainChunker`)

See the full list of options in Setup Configuration.

Common Setups

Cognee + PostgreSQL

PostgreSQL with pgvector is a good production choice for the relational database.Add to your .env:

DB_PROVIDER=postgres
DB_HOST=postgres
DB_PORT=5432
DB_USERNAME=cognee
DB_PASSWORD=cognee
DB_NAME=cognee_db

Start both services:

docker compose --profile postgres up --build

Cognee + PostgreSQL + Neo4j

For production deployments with a dedicated graph database:Add to your .env:

# Relational DB
DB_PROVIDER=postgres
DB_HOST=postgres
DB_PORT=5432
DB_USERNAME=cognee
DB_PASSWORD=cognee
DB_NAME=cognee_db

# Graph DB
GRAPH_DATABASE_PROVIDER=neo4j
GRAPH_DATABASE_URL=bolt://neo4j:7687
GRAPH_DATABASE_NAME=neo4j
GRAPH_DATABASE_USERNAME=neo4j
GRAPH_DATABASE_PASSWORD=pleaseletmein

Start the stack:

docker compose --profile postgres --profile neo4j up --build

Neo4j browser is available at http://localhost:7474.

Cognee + ChromaDB

Use ChromaDB as the vector store:Add to your .env:

VECTOR_DB_PROVIDER=chromadb
VECTOR_DB_URL=http://chromadb:8000
VECTOR_DB_KEY=your_chroma_token

Start:

docker compose --profile chromadb up --build

Cognee with MCP Server

Run the MCP server alongside the API:

docker compose --profile mcp up --build cognee-mcp

The MCP server uses SSE transport on port 8000 (separate container). Configure your IDE to point to http://localhost:8000/sse.

Stopping and Cleaning Up

# Stop containers (preserves volumes)
docker compose down

# Stop and remove volumes (deletes all data)
docker compose down --volumes

Additional Information

Adding optional extras to the Docker image

The default Docker image includes a fixed set of extras from the repository Dockerfile. If you need features behind another optional dependency, add the matching --extra <name> flag to both uv sync lines in the Dockerfile, then rebuild the image.For a table of available extras and common combinations, see Installation. For a table of supported file types and their loaders, see Loaders.Example: adding the docs extra

# First uv sync (--no-install-project):
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --extra debug --extra api --extra postgres --extra neo4j \
             --extra llama-index --extra ollama --extra mistral --extra groq \
             --extra anthropic --extra chromadb --extra docs \
             --frozen --no-install-project --no-dev --no-editable

# Second uv sync (installs the project):
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --extra debug --extra api --extra postgres --extra neo4j \
             --extra llama-index --extra ollama --extra mistral --extra groq \
             --extra anthropic --extra chromadb --extra docs \
             --frozen --no-dev --no-editable

This same pattern works for other extras such as scraping, redis, tracing, monitoring, or docling.Rebuild after updating the Dockerfile:

docker compose up --build cognee

Fixing 'Connection refused' startup errors with PostgreSQL

When Cognee starts before PostgreSQL finishes initializing, the first API call triggers LLM/embedding connectivity checks (setup_and_check_environment) and may hit the database before it accepts connections, producing [Errno 111] Connection refused or [Errno 99] Cannot assign requested address.Recommended fix — add a healthcheck and depends_on condition to your docker-compose.yml:

services:
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: cognee
      POSTGRES_PASSWORD: cognee
      POSTGRES_DB: cognee_db
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cognee -d cognee_db"]
      interval: 10s
      timeout: 5s
      retries: 5

  cognee:
    image: cognee/cognee:main
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DB_PROVIDER: postgres
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USERNAME: cognee
      DB_PASSWORD: cognee
      DB_NAME: cognee_db

This delays the cognee container until PostgreSQL passes its health check.Alternative fix — bypass the connectivity check:If you cannot modify the compose file (e.g. third-party orchestration), set COGNEE_SKIP_CONNECTION_TEST=true to skip the LLM/embedding startup probe entirely. The check is only performed once (on first run), so the trade-off is that misconfigured endpoints are not caught until the first real request.

COGNEE_SKIP_CONNECTION_TEST=true

Enabling office documents and advanced PDF loaders

To use UnstructuredLoader for .docx, .pptx, .xlsx, .epub, and similar formats, add --extra docs as shown above and rebuild the image.That same docs extra also enables AdvancedPdfLoader. For layout-aware or OCR-based PDF extraction, you additionally need poppler-utils and tesseract-ocr in the runtime stage of your Dockerfile (the second FROM python:3.12-slim-bookworm block):

RUN apt-get update && apt-get install -y \
    libpq5 \
    curl \
    poppler-utils \
    tesseract-ocr \
    && rm -rf /var/lib/apt/lists/*

Once rebuilt, the loaders activate automatically for supported file types with no code changes required.

Need help?

Join our community for Docker deployment support.

Self-Hosting

Documentation Index

​Prerequisites

​Quick Start

​Service Profiles

​Data Persistence

​Environment Variables

​Common Setups

​Stopping and Cleaning Up

​Additional Information