DocsGPT/docs/content/upgrading.mdx

---
title: Upgrading DocsGPT
description: Upgrade your DocsGPT deployment across Docker Compose, source builds, and Kubernetes.
---

import { Callout } from 'nextra/components'

# Upgrading DocsGPT

<Callout type="warning">
  **Upgrading from 0.16.x?** User data moved from MongoDB to Postgres in 0.17.0. Follow the [Postgres Migration guide](/Deploying/Postgres-Migration) before running `docker compose pull` or `git pull` — existing deployments will not start cleanly without it.
</Callout>

## Connectors: set ENCRYPTION_SECRET_KEY first

Service credentials (OAuth tokens for Google Drive, SharePoint, Confluence and MCP servers, and API keys for tools) now live on **connections** and are encrypted with a key derived from `ENCRYPTION_SECRET_KEY`. Migration `0040_connections` runs on startup, encrypts the stored tokens and removes their plaintext copies.

<Callout type="warning">
  **Multi-user installs** (any `AUTH_TYPE`): set `ENCRYPTION_SECRET_KEY` to your own value **before** you upgrade, in the environment of the API, the worker and anything that runs migrations. The migration encrypts with the key it sees; changing it afterwards makes every connection ask its owner to reconnect. While the key is still the public default, DocsGPT refuses to store new credentials and Admin > Connectors shows a warning.
</Callout>

If you already used a key and want to change it, see [rotating the key](/Guides/Connectors#encryption-key). Single-user local installs keep working with the default and log a warning at startup.

Other changes:

- Register `CONNECTOR_REDIRECT_BASE_URI` exactly as set (no `?provider=` query) as the redirect URI of each OAuth app. Admin > Connectors shows it.
- `VITE_GOOGLE_CLIENT_ID` is optional now; without it, members pick Drive files in DocsGPT's own picker.
- Synced sources run as their connection, without a browser session. Keep Celery beat running for scheduled syncs.
- Downgrading to `0037_request_traces` decrypts the tokens back and gives each tool its key again.

## pip installs: data home moved

An installed package (`pip install docsgpt`, pipx, `uv tool`) used to keep its data home, meaning `.env`, `inputs/`, `indexes/` and `models/`, in the directory you ran `docsgpt api` and `docsgpt worker` from. It is now `~/.docsgpt/server` (`/opt/docsgpt` for root on Linux). Either move those files there, or set `DOCSGPT_HOME` to the old directory in the environment of both commands. Both commands print the data home they use, and point out a `.env` in the working directory that they no longer read. Source checkouts and the Docker images are not affected.

## Standalone Compose file: one port

The standalone Compose file (`docker-compose-standalone.yaml`) no longer runs a frontend container. The backend image serves the web UI on port 7091, and the port is published on `127.0.0.1` unless you set `DOCSGPT_BIND`. After downloading the new file, start it with `--remove-orphans` to remove the old frontend container, then open port 7091 instead of 5173. If you opened DocsGPT from other machines, see [Upgrading from an earlier standalone file](/Deploying/Docker-Deploying#upgrading-from-an-earlier-standalone-file). The checkout Compose files and the Kubernetes manifests are unchanged.

## Embedding models

DocsGPT now runs embeddings through [FastEmbed](https://github.com/qdrant/fastembed) (ONNX Runtime) instead of SentenceTransformer. The models are the same and the vectors are identical, so **your existing index needs no action** — `all-mpnet-base-v2` keeps working exactly as before.

<Callout type="warning">
  **Your worker command does need one change.** Query embedding now runs on the Celery worker (`EMBEDDINGS_DELEGATE_TO_WORKER`, on by default), which keeps the API from loading a model of its own. If you start your worker with an explicit `-Q`, add the `embeddings` queue:

  ```diff
  - celery -A docsgpt.app.celery worker -l INFO -Q docsgpt,parsing
  + celery -A docsgpt.app.celery worker -l INFO -Q docsgpt,parsing,embeddings
  ```

  The bundled Compose and Kubernetes manifests already do this — pull them along with the code. Without it, every search blocks for `EMBEDDINGS_DELEGATE_TIMEOUT` (60s) and then answers with no retrieved context rather than raising, so the symptom is bad answers, not an error. To keep the model out of the worker too, set `EMBEDDINGS_BASE_URL`; to run the API on its own, set `EMBEDDINGS_DELEGATE_TO_WORKER=false`.
</Callout>

New installs default to `ibm-granite/granite-embedding-311m-multilingual-r2`: multilingual, a 32k-token context, and the same 768 dimensions.

### Switching an existing deployment to granite

<Callout type="error">
  Changing `EMBEDDINGS_NAME` on an index that already has vectors **breaks retrieval silently**. Both models are 768-dimensional, so nothing raises an error — queries are simply compared against vectors that mean something else, and answers quietly get worse. Always re-embed.
</Callout>

Set the model, then rebuild the vectors:

```bash
# 1. In your .env
EMBEDDINGS_NAME=ibm-granite/granite-embedding-311m-multilingual-r2

# 2. Rebuild the vectors from the chunk text already in your index
docker compose exec backend python -m docsgpt.scripts.reembed --dry-run
docker compose exec backend python -m docsgpt.scripts.reembed
```

Re-embedding reads the chunk text already stored in your index. It does not re-download, re-parse or re-chunk your documents, so no source files are needed and the run is proportional to index size, not corpus size. Both `pgvector` and `faiss` are supported.

Useful flags:

| Flag | Effect |
| --- | --- |
| `--dry-run` | Report how many chunks would change, write nothing |
| `--sources a,b` | Only these source ids — also how you retry a failed source |
| `--batch-size N` | Chunks per embed call (default 64) |

The script processes sources independently: one failing source is reported and skipped rather than aborting the run, and the exit code is non-zero if any failed. For `pgvector` it reads a page of chunks at a time and updates rows in place, so memory stays flat on a large index and an interrupted run simply re-does its last batch. For `faiss` it builds the replacement index in memory, writes each file to a temporary path, and moves it into place — so an interrupt during either the rebuild or the write leaves the existing index intact rather than truncated.

<Callout type="warning">
  Stop ingest before you run this. It reads each source's chunks and writes the vectors back; anything ingested while it runs can be overwritten by the rebuild (`faiss`) or missed by it (`pgvector`).
</Callout>

<Callout type="info">
  Running [GraphRAG](/Sources/GraphRAG)? The script also rewrites `graph_nodes.name_embedding`, which seeds every graph traversal. Those vectors are written once at extraction time and share the chunk vectors' width, so leaving them in the old model's space degrades graph retrieval just as silently as the chunk vectors would — and needs no LLM re-extraction to fix.
</Callout>

### Custom local models

A local model now runs through ONNX Runtime, so its repository must ship an ONNX
export (`onnx/model.onnx`) or be one of FastEmbed's built-in models. Repositories
with PyTorch weights only no longer load; `hkunlp/instructor-large`, previously
supported by name, is one of them. Serve such a model over `EMBEDDINGS_BASE_URL`
instead, or switch to a model with an export.

How to run the model — pooling, and whether outputs are L2-normalised — is read
from the repository's own `1_Pooling/config.json` and `modules.json`. Two cases
need attention:

- **Models with a Dense projection layer** (`sentence-transformers/LaBSE`,
  `distiluse-base-multilingual-cased-v1`) are now **refused at startup**.
  FastEmbed cannot apply the projection, so it would have produced vectors of the
  wrong width in a different space. If you were running one, its stored vectors
  were already wrong; move it to `EMBEDDINGS_BASE_URL` or pick another model.
- **Repositories that declare nothing** fall back to mean pooling with
  normalisation and log a warning. Pin the real values with `EMBEDDINGS_POOLING`
  (`cls` or `mean`) and `EMBEDDINGS_NORMALIZE`.

<Callout type="info">
  Staying on `all-mpnet-base-v2` is a supported choice — it remains in the model registry and in `setup.sh`. You only need this section if you want to move to granite.
</Callout>

## Backend package renamed to `docsgpt`

The backend's Python package is `docsgpt` (it was `application`), the name it
will carry on PyPI. For one release the old name keeps working through an
alias, so nothing breaks on upgrade, but update these before the alias goes:

- Entry points: `celery -A docsgpt.app.celery worker`,
  `uvicorn docsgpt.asgi:asgi_app`, `python -m docsgpt.scripts.<name>`. The
  `application.…` spellings still run and print a `FutureWarning`. The
  compose files, Kubernetes manifests and setup scripts in the repository are
  already updated; only custom copies need editing.
- Local image builds: the build context is the repository root, so use
  `docker build -f docsgpt/Dockerfile .` (or the compose files, which do this).
- Celery task names changed with the package (`docsgpt.api.user.tasks.ingest`
  and so on). A worker on this release also accepts the old names, so tasks
  queued before the upgrade still run, and beat rewrites the periodic
  schedule in Redis on start-up. The daily, weekly and monthly source-sync
  timers restart from the upgrade, so the first sync after it can land later
  than it would have (a monthly sync by up to a month). Nothing to do.
- Data directories do not move: the compose files keep your indexes, inputs
  and vectors under `application/` in the checkout, where they already are.
- The backend is also a package now (`pip install docsgpt`, see
  [Install with pip](/Deploying/Pip-Install)). Runtime data lives in a data
  home: `DOCSGPT_HOME`, else the checkout, else `~/.docsgpt/server`
  (`/opt/docsgpt` for root on Linux; see
  [pip installs: data home moved](#pip-installs-data-home-moved)). One consequence for a source checkout: the embedded Milvus
  (`MILVUS_URI`) and LanceDB (`LANCEDB_PATH`) default paths now resolve under
  the checkout instead of the start directory. If you use either store at its
  default path and start DocsGPT from another directory, the old data is at
  `<start directory>/milvus_local.db` or `<start directory>/data/lancedb`;
  point the setting at it, or move it into the checkout. Faiss indexes and
  uploads were already stored under the checkout and are unaffected.

## Check your version

```bash
docker compose exec backend python -c "from docsgpt.version import get_version; print(get_version())"
```

Release notes: [changelog](/changelog). Tags: [GitHub releases](https://github.com/arc53/DocsGPT/releases).

## Docker Compose — hub images

```bash
cd DocsGPT/deployment
docker compose -f docker-compose-hub.yaml pull
docker compose -f docker-compose-hub.yaml up -d
```

`pull` fetches the latest image for whichever tag your compose file references. To move to a specific release, edit `image: arc53/docsgpt:<tag>` first.

## Docker Compose — from source

```bash
cd DocsGPT
git pull
docker compose -f deployment/docker-compose.yaml build
docker compose -f deployment/docker-compose.yaml up -d
```

Swap `git pull` for `git checkout <tag>` if you want to pin a specific release.

## Kubernetes

```bash
kubectl set image deployment/docsgpt-backend backend=arc53/docsgpt:<tag>
kubectl set image deployment/docsgpt-worker worker=arc53/docsgpt:<tag>
kubectl rollout status deployment/docsgpt-backend
kubectl rollout status deployment/docsgpt-worker
```

Full manifests: [Kubernetes deployment guide](/Deploying/Kubernetes-Deploying).

## Migrations

Alembic migrations run on worker startup. To apply manually:

```bash
docker compose exec backend alembic -c docsgpt/alembic.ini upgrade head
```

`upgrade head` is idempotent.

## Rollback

Set the image tag to the previous release and `up -d` again. Schema changes are not reversible without a backup — take one before upgrading any release that mentions migrations in the changelog.