---
layout: 'page'
uri: '/deployment/docker-compose-setup'
position: 2
slug: 'deployment-docker-compose-setup'
parent: 'deployment'
navTitle: 'Docker Compose'
title: 'Docker Compose setup'
description: 'Local development setup with Docker Compose and live file changes.'
---

# Docker Compose setup

Docker Compose is the recommended way to run Documan locally during development. Your docs are mounted as a volume, so changes are picked up immediately after re-importing.

For production builds with validation, see [Docker setup](/deployment/docker-setup). For CI/CD pipelines, see [CI/CD integration](/deployment/ci-cd-integration).


## Quick start

The fastest way to set up everything is the interactive quickstart:

```bash
curl -fsSL https://raw.githubusercontent.com/documan-ai/documan/main/scripts/quickstart.sh | bash
```

It creates all the files below, starts the container, and runs the initial import. If you prefer to set things up manually, follow the steps below.


## Prerequisites

- [Docker](https://docs.docker.com/get-docker/) with Docker Compose v2


## Step 1: Create the Dockerfile

Create the [Dockerfile](/deployment/docker-setup) at `docker/documan/Dockerfile`. This is the same Dockerfile used for production builds and [CI/CD](/deployment/ci-cd-integration). During local development, the volume mount overrides the copied docs — you run import manually after editing.


## Step 2: Create the environment file

Create `.env` in your project root:

```bash
DOCUMAN_PROJECT_NAME='My Docs'
DOCUMAN_HTTP_PORT=3000
DOCUMAN_OPENAI_API_KEY=
DOCUMAN_LICENSE_KEY=
```

See [Configuration](/configuration) for all available variables.


## Step 3: Add the service to docker-compose.yml

Add the `documan` service to your `docker-compose.yml`:

```yaml
services:
  documan:
    build:
      context: .
      dockerfile: ./docker/documan/Dockerfile
    env_file:
      - .env
    ports:
      - "${DOCUMAN_HTTP_PORT}:${DOCUMAN_HTTP_PORT}"
    volumes:
      - ./docs:/documan/data/docs
```


## Step 4: Build and start

For the first build, skip validation steps (your docs may not have frontmatter yet):

```bash
docker compose build --build-arg SKIP_BUILD_STEPS=true documan
docker compose up -d documan
```

Subsequent builds validate normally:

```bash
docker compose up -d documan --build
```


## Step 5: Fix and import

After starting the container, fix frontmatter and import your docs:

```bash
# Auto-fix missing frontmatter fields
docker compose exec -t documan /documan/bin/documan fix

# Import docs into Documan
docker compose exec -t documan /documan/bin/documan import
```

Your site is now available at `http://localhost:3000` (or whichever port you configured).


## Daily workflow

After editing any markdown file in `docs/`, re-import to see changes:

```bash
# Re-import after editing docs
docker compose exec -t documan /documan/bin/documan import

# Auto-fix frontmatter (run before committing)
docker compose exec -t documan /documan/bin/documan fix

# Validate docs without modifying
docker compose exec -t documan /documan/bin/documan lint

# Vectorize for semantic search (requires DOCUMAN_OPENAI_API_KEY)
docker compose exec -t documan /documan/bin/documan vectorize
```

If you use Makefile, the [quickstart](/) can add shortcut targets (`make documan`, `make documan-import`, `make documan-fix`, `make documan-lint`, `make documan-vectorize`) so you don't have to type the full docker compose commands.

See [Commands](/getting-started/commands) for details on each command.

---

[← Docker setup](/deployment/docker-setup.md) | [CI/CD integration →](/deployment/ci-cd-integration.md)