Docker Deployment of DocsGPT

Docker is the recommended method for deploying DocsGPT, providing a consistent and isolated environment for the application to run. This guide will walk you through deploying DocsGPT using Docker and Docker Compose.

Prerequisites

Docker Engine: You need to have Docker Engine installed on your system.
- macOS: Docker Desktop for Mac
- Linux: Docker Engine Installation Guide (follow instructions for your specific distribution)
- Windows: Docker Desktop for Windows (requires WSL 2 backend, see notes below)
Docker Compose 2.24 or newer: Docker Desktop includes it. With Docker Engine, install the Compose plugin (docker compose version shows the version). The standalone Compose file uses env_file entries with required: false, which older versions reject, and docsgpt up refuses to run on them.

Important Note for Windows Users: Docker Desktop on Windows needs the WSL 2 backend. Ensure WSL 2 is enabled and configured in Docker Desktop settings.

Run it with `docsgpt up`

The docsgpt Python package can set up and run the stack described below for you. It needs Docker with Compose 2.24 or newer. The installer gets uv , installs the package with it and runs docsgpt up:

macOS and Linux:


curl -fsSL https://docs.ac/install | bash

Windows (PowerShell):


irm https://docs.ac/install.ps1 | iex

Both scripts are attached to every release as install.sh and install.ps1. To install the package yourself instead (Python 3.12 or newer; uv brings one when it is missing):


uv tool install docsgpt      # or: pipx install docsgpt
docsgpt up

docsgpt up keeps the stack in ~/.docsgpt/server (/opt/docsgpt when run as root on Linux; --dir or DOCSGPT_HOME choose another folder): the Compose file of the installed version, a .env with your settings and the generated secrets, and install.json. Data lives in named Docker volumes. The first run asks two questions:

Who should reach DocsGPT: only this computer; other machines on the network (plain HTTP, with AUTH_TYPE=simple_jwt and an access token); or a domain name with HTTPS (Caddy gets the certificate, access token as well).
Which model provider: the DocsGPT public API (no key needed), OpenAI, Anthropic, Google Gemini, OpenRouter, Groq, or an OpenAI-compatible server such as Ollama or vLLM.

Flags answer the same questions, for scripts and servers:


docsgpt up --yes --domain docs.example.com --provider openai --api-key "$OPENAI_API_KEY"

Running docsgpt up again is safe: it keeps .env and the secrets and runs the images of the installed package version. docsgpt up --reconfigure asks the questions again.

docsgpt up also sets API_URL in .env to the address it prints (https://<domain>, or http://<this machine's address>:<port> on the network; http://localhost:<port> for a local install on a port other than 7091), since the backend builds agent image, webhook, device pairing and MCP OAuth callback links from it. It keeps a value you set yourself, such as the public address of your own reverse proxy.

Command	What it does
`docsgpt status`	Version, address, containers, and whether the API answers
`docsgpt logs [-f] [service]`	Container logs
`docsgpt env set KEY=VALUE`	Change a setting; `docsgpt up` applies it
`docsgpt upgrade`	Upgrade the package (for `uv tool` installs) and restart on the new version
`docsgpt down`	Stop the stack; data and settings stay

The docsgpt CLI reference lists every command, including token, restart, doctor, env get, backup, restore and uninstall.

Backups

docsgpt backup writes one archive holding a dump of the database and a tar of each data volume (indexes, inputs, vectors). It is new after 0.21.0; on 0.21.0, back up by hand.


docsgpt backup                      # into <stack>/backups
docsgpt backup --out /mnt/backups   # somewhere else, e.g. a mounted disk

While the archive is made, the backend and the worker stop and start again, so the database dump and the files in the volumes describe the same moment; Postgres itself keeps running. On a small install that pause is seconds, but count on it if you run docsgpt backup from cron. The archive is written readable only by the user who took it.

The archive does not include .env, because that file holds the install’s secrets. docsgpt backup --with-settings puts it in, for when the archive itself is stored somewhere private. Keep .env safe separately otherwise: the database password in it is what an existing Postgres volume expects.

Restoring replaces the data in an install:


docsgpt restore ~/.docsgpt/server/backups/docsgpt-20260916-120000.tar.gz

It asks first, then stops the stack, puts the volumes and the database back, and starts DocsGPT again. The backup loads into an empty database, so tables a newer release added go too; the current database is kept as docsgpt_before_restore until the load succeeds, and put back if it fails. --yes skips the question for scripts. A backup taken with a newer DocsGPT is refused, since its data may not fit this version’s schema; upgrade first, or pass --force if you know the two match.

The Postgres data directory itself is not archived: the dump is the database backup, and copying a directory Postgres is writing to would capture a torn copy. Caddy’s certificates are not archived either, as it obtains them again.

More docsgpt up options: --port, --docling (the image with the docling parser engine and OCR), --image-tag develop (follow the main branch) and --adopt (manage a stack you started from the standalone Compose file in another folder; both use the same data volumes). For Ollama on the same machine, use the base URL http://host.docker.internal:11434/v1; on Linux, also make Ollama listen beyond localhost (OLLAMA_HOST=0.0.0.0).

Quickest Setup: Pre-built Images, No Checkout

Every release publishes ready-to-run images to Docker Hub (arc53/docsgpt, arc53/docsgpt-fe) and GitHub Container Registry (ghcr.io/arc53/docsgpt, ghcr.io/arc53/docsgpt-fe) for linux/amd64 and linux/arm64. arc53/docsgpt runs the API, serves the web UI and runs the worker; arc53/docsgpt-fe is the separate frontend image the checkout Compose files and Kubernetes use. The images contain everything the default configuration needs (embedding models, tokenizers, tiktoken’s encoding), so a fresh container makes no downloads on first use. You do not need the source tree to run them:

Download the standalone Compose file (also attached to every release ):


mkdir docsgpt && cd docsgpt
curl -fsSLO https://raw.githubusercontent.com/arc53/DocsGPT/main/deployment/docker-compose-standalone.yaml

Create a .env next to it with your settings, for example the public API:
```
printf 'LLM_PROVIDER=docsgpt\nVITE_API_STREAMING=true\nINTERNAL_KEY=%s\nENCRYPTION_SECRET_KEY=%s\n' \
  "$(openssl rand -hex 16)" "$(openssl rand -hex 32)" > .env
```
INTERNAL_KEY is the secret the worker uses to hand finished indexes to the API; without it every upload fails with a 401. setup.sh generates one for you, a hand-written .env has to include it. ENCRYPTION_SECRET_KEY seals the credentials of the services you connect; set it on a fresh install only (see Secrets to set before going live). This stack runs the granite embedding model unless .env sets EMBEDDINGS_NAME; both granite and mpnet are baked into the image.
Start it:
```
docker compose -f docker-compose-standalone.yaml up -d
```
Then open http://localhost:7091/ . The web UI and the API share that port, which is published on 127.0.0.1: only this machine can reach it until you change DOCSGPT_BIND (below). Data lives in named Docker volumes; docker compose -f docker-compose-standalone.yaml down keeps it and down -v removes it.

Tags and variants. DOCSGPT_IMAGE_TAG picks the version: a release such as 0.21.0, latest (the newest release, the default here) or develop (follows the main branch). DOCSGPT_IMAGE_VARIANT picks the flavour: empty for the slim default image, or -docling for the image with the docling parser engine, its models and tesseract baked in (needed for OCR of scanned documents, see the OCR guide). Both are read from .env or the shell, e.g. DOCSGPT_IMAGE_TAG=0.21.0 DOCSGPT_IMAGE_VARIANT=-docling. The same two variables drive deployment/docker-compose-hub.yaml in a checkout, but there the default tag is develop; see Using the Source Checkout.

Opening it from other machines

Publish the port on every interface and turn on authentication in .env:


DOCSGPT_BIND=0.0.0.0
# The address other machines open, for the links the backend builds
API_URL=http://<server-address>:7091
AUTH_TYPE=simple_jwt
JWT_SECRET_KEY=<a long random value, e.g. openssl rand -hex 32>
# With AUTH_TYPE set, connecting services needs it. Fresh install only: an
# existing one rotates onto it (App Configuration, Secrets to set before going live)
ENCRYPTION_SECRET_KEY=<a long random value, e.g. openssl rand -hex 32>

The backend builds agent image, agent webhook, device pairing and MCP OAuth callback links from API_URL. Unset, they point at http://localhost:7091, which other machines can’t open. The worker keeps API_URL=http://backend:7091 from the Compose file, which takes precedence over .env, so it still reaches the backend directly.

simple_jwt is one shared token for one shared user: everyone who has it sees the same conversations and sources. For separate accounts use AUTH_TYPE=oidc, and see the security checklist.

Then run docker compose -f docker-compose-standalone.yaml up -d again. The UI takes its API address from the page it was loaded from, so http://<server-address>:7091/ works without further settings. Without AUTH_TYPE, anyone who can reach the port can use DocsGPT.

With simple_jwt the UI asks for a token, which the backend prints when it starts: docker compose -f docker-compose-standalone.yaml logs backend | grep "Simple JWT". The token is signed with JWT_SECRET_KEY. Without that setting each container generates its own secret, and a re-created container (after pull or a settings change) gets a new one and so a new token. Over plain HTTP the token travels as readable text; outside a trusted network, use HTTPS as below. DOCSGPT_PORT changes the host port (default 7091). See Authentication Settings for the other modes.

HTTPS with your own domain

The Compose file has an optional Caddy service that obtains and renews a Let’s Encrypt certificate and proxies to the backend.

Point the domain’s DNS records at the machine and open ports 80 and 443.

Add to .env:


COMPOSE_PROFILES=https
DOCSGPT_DOMAIN=docs.example.com
API_URL=https://docs.example.com
AUTH_TYPE=simple_jwt
JWT_SECRET_KEY=<a long random value, e.g. openssl rand -hex 32>
# Fresh install only; an existing one rotates onto it
ENCRYPTION_SECRET_KEY=<a long random value, e.g. openssl rand -hex 32>

Run docker compose -f docker-compose-standalone.yaml up -d and open https://docs.example.com/.

COMPOSE_PROFILES=https in .env makes every later up, down and logs include Caddy. Leave DOCSGPT_BIND at its default: Caddy reaches the backend over the Compose network.

Database password

The Postgres password defaults to docsgpt; the database is only reachable inside the Compose network. To use your own, set POSTGRES_PASSWORD in .env before the first start, with URL-safe characters (e.g. openssl rand -hex 24). Postgres reads it only when its volume is created, so changing it later does not change the existing database’s password.

Upgrading from an earlier standalone file

Before this change the standalone file ran a separate frontend container on port 5173 and published both ports on every interface. After downloading the new file:


docker compose -f docker-compose-standalone.yaml pull
docker compose -f docker-compose-standalone.yaml up -d --remove-orphans

--remove-orphans removes the old frontend container. Open port 7091 instead of 5173. Your data volumes are unchanged. If you opened DocsGPT from other machines, follow Opening it from other machines, and remove VITE_API_HOST from .env if it points at localhost: the UI would otherwise keep calling the visitor’s own machine.

Using the Source Checkout

With a clone of the repository, deployment/docker-compose-hub.yaml runs the same pre-built images while keeping your data in application/indexes, application/inputs and application/vectors, and deployment/docker-compose.yaml builds the images from your working tree (for local changes, or a build with extra packages: EXTRAS=docling in .env).

Run every Compose command from the repository root with --env-file .env. Compose fills the ${...} values in these files (the image tag, EXTRAS, DOCSGPT_BIND, the VITE_* build arguments) from a .env in the directory of the Compose file, which is deployment/, not the root. The env_file: ../.env entries only pass settings into the containers. Without --env-file .env, a pinned DOCSGPT_IMAGE_TAG or EXTRAS=docling is ignored.

Image tag. docker-compose-hub.yaml, which setup.sh and setup.ps1 run, defaults to the develop images, built from the main branch, not to the latest release. For anything beyond trying DocsGPT out, pin a release in .env:


DOCSGPT_IMAGE_TAG=0.21.0

Pin it through the variable, not by editing image: in the file: the variable sets the backend, worker and frontend images together.

⚠️

The checkout Compose files (and setup.sh/setup.ps1, which run them) are meant for local use and development. They publish the API (7091) and the UI (5173) on DOCSGPT_BIND, 127.0.0.1 by default, and Postgres (password docsgpt) and Redis (no password) on 127.0.0.1 only. Setting DOCSGPT_BIND=0.0.0.0 makes the API and UI reachable from the network; without AUTH_TYPE every visitor then shares one account, with its data and connected services. Other machines open the API port, http://<server-address>:7091, which serves the UI too; also set API_URL to that address (or your proxy’s public https:// address) in .env so the links the backend builds work from there. The worker keeps http://backend:7091 from the Compose file. When the setup scripts expose DocsGPT, they ask for this address and write it. For a server, prefer docsgpt up or the standalone file, and follow the security checklist.

Clone the DocsGPT Repository (if you haven’t already):


git clone https://github.com/arc53/DocsGPT.git
cd DocsGPT

Create a .env file:

In the root directory of your DocsGPT repository, create a file named .env.
Add Public API Configuration to .env:

Open the .env file and add the following lines:
```
LLM_PROVIDER=docsgpt
VITE_API_STREAMING=true
INTERNAL_KEY=<any random string, e.g. openssl rand -hex 16>
EMBEDDINGS_NAME=ibm-granite/granite-embedding-311m-multilingual-r2
```
This minimal configuration tells DocsGPT to use the public API. The EMBEDDINGS_NAME line is what setup.sh writes for a new install; without it the code falls back to mpnet, the model earlier releases indexed with, so that an upgraded deployment keeps its existing index working. For more advanced settings and other LLM options, refer to the DocsGPT Settings Guide.
Launch DocsGPT with Docker Compose:

Navigate to the root directory of the DocsGPT repository in your terminal and run:
```
docker compose --env-file .env -f deployment/docker-compose-hub.yaml up -d
```
The -d flag runs Docker Compose in detached mode (in the background). To build the images from your working tree instead of pulling them:
```
docker compose --env-file .env -f deployment/docker-compose.yaml up --build -d
```
Access DocsGPT in your browser:

Once the containers are running, open your web browser and go to http://localhost:5173/ . With DOCSGPT_BIND=0.0.0.0, other machines open http://<server-address>:7091/: the backend image serves the UI there too, while the UI on 5173 calls the API at localhost.
Stopping DocsGPT:

To stop the application, run from the repository root:
```
docker compose --env-file .env -f deployment/docker-compose-hub.yaml down
```
Use the same -f files you started it with (docker-compose.yaml for a build, plus any Ollama overlay). Other commands take the same form, for example docker compose --env-file .env -f deployment/docker-compose-hub.yaml logs -f backend.

Optional Ollama Setup (Local Models)

DocsGPT provides optional Docker Compose files to easily integrate with Ollama for running local models. These files add an official Ollama container to your Docker Compose setup. These files are located in the deployment/optional/ directory.

There are two Ollama optional files:

docker-compose.optional.ollama-cpu.yaml: For running Ollama on CPU.
docker-compose.optional.ollama-gpu.yaml: For running Ollama on GPU (requires Docker to be configured for GPU usage).

Launching with Ollama and Pulling a Model

Clone the DocsGPT Repository and create .env pointing at Ollama.

Clone the repository as described above, but put these lines in .env instead of the public API block. Without them DocsGPT keeps sending chats to the public DocsGPT API, even with the Ollama container running:
```
LLM_PROVIDER=openai
OPENAI_BASE_URL=http://ollama:11434/v1
LLM_NAME=llama3.2:1b
API_KEY=None
VITE_API_STREAMING=true
INTERNAL_KEY=<any random string, e.g. openssl rand -hex 16>
EMBEDDINGS_NAME=ibm-granite/granite-embedding-311m-multilingual-r2
```
ollama is the service the overlay adds, reachable from the DocsGPT containers by that name. LLM_NAME is the model you pull in step 3; it is required, and several models can be listed separated by commas. See Local Inference for the other settings.

The overlays only fit the Compose files in the checkout. With the standalone Compose file or docsgpt up (Docker mode), run Ollama on the host instead and use OPENAI_BASE_URL=http://host.docker.internal:11434/v1 (on Linux, also make Ollama listen beyond localhost with OLLAMA_HOST=0.0.0.0). With docsgpt up --native, DocsGPT runs on the host itself, so use OPENAI_BASE_URL=http://localhost:11434/v1.

Launch DocsGPT with Ollama Docker Compose:

Choose the appropriate Ollama Compose file (CPU or GPU) and launch DocsGPT:

CPU:


docker compose --env-file .env -f deployment/docker-compose-hub.yaml -f deployment/optional/docker-compose.optional.ollama-cpu.yaml up -d

GPU:


docker compose --env-file .env -f deployment/docker-compose-hub.yaml -f deployment/optional/docker-compose.optional.ollama-gpu.yaml up -d

Pull the Ollama Model:

Crucially, after launching with Ollama, you need to pull the desired model into the Ollama container. Use the LLM_NAME from your .env file (llama3.2:1b in the example above) and run this command to pull the model inside the running Ollama container:


docker compose --env-file .env -f deployment/docker-compose-hub.yaml -f deployment/optional/docker-compose.optional.ollama-cpu.yaml exec -it ollama ollama pull <LLM_NAME>

or (for GPU):


docker compose --env-file .env -f deployment/docker-compose-hub.yaml -f deployment/optional/docker-compose.optional.ollama-gpu.yaml exec -it ollama ollama pull <LLM_NAME>

Replace <LLM_NAME> with the actual model name from your .env file.

Access DocsGPT in your browser:

Once the model is pulled and containers are running, open your web browser and go to http://localhost:5173/ .

Stopping Ollama Setup:

To stop a DocsGPT setup launched with Ollama optional files, use docker compose down and include all the compose files used during the up command:


docker compose --env-file .env -f deployment/docker-compose-hub.yaml -f deployment/optional/docker-compose.optional.ollama-cpu.yaml down


docker compose --env-file .env -f deployment/docker-compose-hub.yaml -f deployment/optional/docker-compose.optional.ollama-gpu.yaml down

Important for GPU Usage:

NVIDIA Container Toolkit (for NVIDIA GPUs): If you are using NVIDIA GPUs, you need to have the NVIDIA Container Toolkit installed and configured on your system for Docker to access your GPU.
Docker GPU Configuration: Ensure Docker is configured to utilize your GPU. Refer to the Ollama Docker Hub page and Docker documentation for GPU setup instructions specific to your GPU type (NVIDIA, AMD, Intel).

Optional Code Execution Sandbox

The Artifact and Code Executor tools need a sandbox runner, which the checkout Compose files add as another overlay (deployment/optional/docker-compose.optional.sandbox.yaml, plus an optional egress overlay). It needs a SANDBOX_GATEWAY_AUTH_TOKEN in .env. The docsgpt up install has no sandbox option. See Code Execution Sandbox for the commands and the isolation caveats.

Restarting After Configuration Changes

Whenever you modify the .env file or any Docker Compose files, recreate the containers for the changes to be applied: run the same docker compose ... up -d command you used to launch DocsGPT, with --env-file .env and every -f file (including optional overlays) for a checkout. Compose recreates the containers whose settings changed. With docsgpt up, run docsgpt up again.

Further Configuration

This guide covers the basic Docker deployment of DocsGPT. For detailed information on configuring various aspects of DocsGPT, such as LLM providers, models, vector stores, and more, please refer to the comprehensive DocsGPT Settings Guide.