How to Set Up DeepWiki Using Docker: Environment Variables and Volume Mounting Guide

To set up DeepWiki using Docker, clone the repository, create a .env file with your API keys, and run docker-compose up --build to launch the multi-service container with persistent volumes mounted.

DeepWiki is an open-source documentation generator that combines a Python FastAPI backend with a Next.js frontend. This guide walks you through the complete process to set up DeepWiki using Docker, including configuring environment variables and mounting persistent volumes for data retention.

Prerequisites

Before you begin, ensure you have Docker and Docker Compose installed on your system. You will also need API keys for at least one supported provider (Google, OpenAI, OpenRouter, Azure, or Ollama) to enable the language model and embedding functionality.

Step 1: Clone the DeepWiki Repository

Start by cloning the official repository and navigating into the project directory:

git clone https://github.com/AsyncFuncAI/deepwiki-open.git
cd deepwiki-open

The repository contains the Dockerfile and docker-compose.yml files necessary for building the multi-stage image that packages both the backend (port 8001) and frontend (port 3000) services.

Step 2: Configure Environment Variables

DeepWiki requires specific environment variables to authenticate with AI providers and configure the application behavior. Create a .env file in the project root with your chosen configuration.

Required API Keys

Only the variables corresponding to your selected model provider are mandatory:

Variable	Purpose	Required For
GOOGLE_API_KEY	Google Gemini and Google AI embeddings	Google models
OPENAI_API_KEY	OpenAI models and embeddings	OpenAI models
OPENROUTER_API_KEY	OpenRouter models	OpenRouter
AZURE_OPENAI_API_KEY	Azure OpenAI authentication	Azure OpenAI
AZURE_OPENAI_ENDPOINT	Azure OpenAI service URL	Azure OpenAI
AZURE_OPENAI_VERSION	Azure API version	Azure OpenAI

Optional Configuration Variables

Additional variables control embedding providers, logging, and authentication:

• DEEPWIKI_EMBEDDER_TYPE: Select embedder type (openai, google, ollama, bedrock). Defaults to openai.
• OLLAMA_HOST: URL for remote Ollama server (defaults to http://localhost:11434).
• PORT: API server port (defaults to 8001).
• SERVER_BASE_URL: Base URL for API used by the frontend.
• LOG_LEVEL and LOG_FILE_PATH: Control logging verbosity and output location.
• DEEPWIKI_AUTH_MODE and DEEPWIKI_AUTH_CODE: Optional authorization gate configuration.

Example .env file using Google embeddings and OpenAI generation:

cat > .env <<EOF
GOOGLE_API_KEY=your_google_api_key
OPENAI_API_KEY=your_openai_api_key
DEEPWIKI_EMBEDDER_TYPE=google
PORT=8001
LOG_LEVEL=INFO
EOF

Step 3: Build and Launch the Container

You can deploy DeepWiki using Docker Compose (recommended) or manual Docker commands.

Using Docker Compose (Recommended)

The docker-compose.yml file handles environment injection, volume mounting, and port mapping automatically:

docker-compose up --build

This command reads the .env file via the env_file: directive, builds the multi-stage image defined in the Dockerfile, and starts the container with persistent storage mounted.

Manual Docker Build and Run

For manual deployment without Docker Compose:

# Build the image locally

docker build -t deepwiki-open .

# Run with volume mounts and environment variables

docker run -p 8001:8001 -p 3000:3000 \
  --env-file .env \
  -v ~/.adalflow:/root/.adalflow \
  -v $(pwd)/api/logs:/app/api/logs \
  deepwiki-open

Step 4: Configure Volume Mounting for Persistent Storage

DeepWiki requires specific volume mounts to ensure data persists across container restarts and to store application logs.

AdalFlow Cache Directory

The ~/.adalflow directory on your host maps to /root/.adalflow inside the container. This volume stores:

• Cloned repository data
• Generated embeddings
• Cached wiki content

Mount configuration in docker-compose.yml:

volumes:
  - ~/.adalflow:/root/.adalflow

Application Logs

The ./api/logs directory on your host maps to /app/api/logs in the container. This ensures log files survive container recreation and are accessible from the host for debugging.

Mount configuration:

volumes:
  - ./api/logs:/app/api/logs

These mounts are defined in the docker-compose.yml file and ensure that heavy data operations do not require rebuilding or re-downloading content when the container restarts.

Step 5: Access the Application

Once the container is running, access DeepWiki at:

• Backend API: http://localhost:8001 (or the port specified in your PORT environment variable)
• Frontend UI: http://localhost:3000

Both ports are exposed in the Dockerfile (EXPOSE ${PORT:-8001} 3000) and mapped in docker-compose.yml using the syntax - "${PORT:-8001}:${PORT:-8001}" for the API and - "3000:3000" for the frontend.

Optional: Custom SSL Certificates

If you need to trust self-signed Certificate Authorities, place your certificate files in a certs/ directory and build the image with the CUSTOM_CERT_DIR build argument:

docker build --build-arg CUSTOM_CERT_DIR=certs -t deepwiki-open .

The Dockerfile installs any certificates found in the specified directory into the container's trust store, enabling secure connections to internal services or private registries.

Summary

• DeepWiki combines a Python FastAPI backend (port 8001) and Next.js frontend (port 3000) in a single multi-stage Docker image.
• Environment variables in a .env file configure API keys for Google, OpenAI, OpenRouter, Azure, or Ollama, plus optional settings for embedders and logging.
• Volume mounting persists data via ~/.adalflow:/root/.adalflow (cached repos and embeddings) and ./api/logs:/app/api/logs (application logs).
• Docker Compose is the recommended deployment method, handling build, environment injection, and volume mapping automatically.
• Access the running application at localhost:8001 for the API and localhost:3000 for the web interface.

Frequently Asked Questions

What ports does DeepWiki expose when running in Docker?

DeepWiki exposes two ports: 8001 for the Python FastAPI backend (configurable via the PORT environment variable) and 3000 for the Next.js frontend. These are defined in the Dockerfile using EXPOSE ${PORT:-8001} 3000 and mapped to host ports in docker-compose.yml.

Can I use Ollama for local embeddings with DeepWiki Docker setup?

Yes. Set the DEEPWIKI_EMBEDDER_TYPE environment variable to ollama and specify your Ollama server URL using OLLAMA_HOST (defaults to http://localhost:11434). If running Ollama on the host machine from within Docker, use host.docker.internal as the host address or run Ollama on a network-accessible address.

How do I persist DeepWiki data across container restarts?

Mount two specific volumes in your docker-compose.yml or docker run command: map ~/.adalflow to /root/.adalflow to preserve cloned repositories and embedding caches, and map ./api/logs to /app/api/logs to retain application logs. These mounts ensure data survives container recreation and updates.

Is Docker Compose required to run DeepWiki?

No, Docker Compose is recommended but not required. You can build and run the container manually using docker build -t deepwiki-open . followed by docker run with the appropriate port mappings (-p 8001:8001 -p 3000:3000), environment file (--env-file .env), and volume mounts (-v ~/.adalflow:/root/.adalflow -v $(pwd)/api/logs:/app/api/logs).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}