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

> Setting up DeepWiki with Docker is simple. Clone the repo, configure environment variables in a .env file, and launch with docker-compose up for persistent volumes. Get started now.

- Repository: [ASYNCFUNC/deepwiki-open](https://github.com/asyncfuncai/deepwiki-open)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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:

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

```

The repository contains the `Dockerfile` and [`docker-compose.yml`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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:

```bash
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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/docker-compose.yml) file handles environment injection, volume mounting, and port mapping automatically:

```bash
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:

```bash

# 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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/docker-compose.yml):

```yaml
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:

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

```

These mounts are defined in the [`docker-compose.yml`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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:

```bash
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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`).