Setting Up a Development Environment

This guide will walk you through setting up a development environment for DocsGPT. This setup allows you to modify and test the application’s backend and frontend components.

1. Spin Up Postgres and Redis

For development purposes, you can quickly start Postgres and Redis containers. Postgres is the user-data store for DocsGPT (conversations, agents, prompts, sources, attachments, workflows, logs, and token usage), and Redis is used as the cache and Celery broker. We provide a dedicated Docker Compose file, docker-compose-dev.yaml, located in the deployment directory, that includes only these essential services. The backend applies the Alembic schema automatically on first boot (AUTO_MIGRATE=true / AUTO_CREATE_DB=true ship enabled), so no separate migration step is required. You can still run python scripts/db/init_postgres.py explicitly if you prefer.

You can find the docker-compose-dev.yaml file here .

Steps to start Postgres and Redis:

1. Navigate to the root directory of your DocsGPT repository in your terminal.

2. Run the following commands to build and start the containers defined in docker-compose-dev.yaml:

   docker compose -f deployment/docker-compose-dev.yaml build
   docker compose -f deployment/docker-compose-dev.yaml up -d

   These commands will start Postgres and Redis in detached mode, running in the background. When the Flask backend boots against the fresh Postgres instance, it will automatically create the database (if missing) and apply the current Alembic schema.

2. Run the Backend

To run the DocsGPT backend locally, you’ll need to set up a Python environment and install the necessary dependencies.

Prerequisites:

• Python 3.12: Ensure you have Python 3.12 installed on your system. You can check your Python version by running python --version or python3 --version in your terminal.

Steps to run the backend:

1. Configure Environment Variables:

   DocsGPT backend settings are configured using environment variables. You can set these either in a .env file or directly in the settings.py file. For a comprehensive overview of all settings, please refer to the DocsGPT Settings Guide.

   • Option 1: Using a .env file (Recommended):

     • If you haven’t already, create a file named .env in the root directory of your DocsGPT project.
     • Modify the .env file to adjust settings as needed. You can find a comprehensive list of configurable options in docsgpt/core/settings.py.

   • Option 2: Exporting Environment Variables:

     • Alternatively, you can export environment variables directly in your terminal. However, using a .env file is generally more organized for development.

2. Create a Python Virtual Environment (Optional but Recommended):

   Using a virtual environment isolates project dependencies and avoids conflicts with system-wide Python packages.

   • macOS and Linux:

     python -m venv venv
     . venv/bin/activate

   • Windows:

     python -m venv venv
      venv/Scripts/activate

3. Embedding Model (no action needed):

   The embedding model is downloaded automatically the first time you ingest a document, and cached for subsequent runs under models/ in the data home: the repository root, unless DOCSGPT_HOME points elsewhere. Set EMBEDDINGS_CACHE_DIR to use another directory.

   For an offline or air-gapped machine, fetch it ahead of time instead:

   python -m docsgpt.scripts.prefetch_models

4. Install Backend Dependencies:

   Navigate to the root of your DocsGPT repository and install the required Python packages:

   pip install -r docsgpt/requirements.txt

   Dependencies are declared in pyproject.toml and locked in uv.lock; the requirements*.txt files are exported from that lock, so with uv  installed uv sync sets up the same environment (plus the test tools) in one step.

   Optional extras are not installed by default. Add them when you need the feature (each file is the core set plus the extra):

   pip install -r docsgpt/requirements-docling.txt   # docling parser engine: OCR backend, read_document structured output
   pip install -r docsgpt/requirements-milvus.txt    # VECTOR_STORE=milvus
   # or with uv: uv sync --extra docling --extra milvus

   The docling file adds the PyTorch CPU index; pip handles that as-is, while uv pip install -r needs UV_INDEX_STRATEGY=unsafe-best-match (or use uv sync --extra docling, which reads the lock).

   A feature whose extra is missing fails with the exact command to run. After changing pyproject.toml, run uv lock and bash scripts/export_requirements.sh so the exported files stay in sync (CI checks this).

5. Run the Backend:

   One command runs the API and the worker from this checkout, each restarting when you save a file:

   docsgpt dev

   Both run as children of that terminal, with their output interleaved and labelled, and Ctrl-C stops them together. Useful flags:

   Flag	What it does
   --ui	also start the Vite dev server, so the whole app runs from one command
   --mock-llm	run scripts/mock_llm.py and point DocsGPT at it, so no API key is needed
   --no-worker	leave the worker to you, for instance when debugging it in your editor
   --no-reload	do not restart anything on save
   --port	serve the API somewhere other than 7091

   docsgpt dev is for a checkout. docsgpt up --native, by contrast, installs supervised services that outlive the shell — see Run it as services.

   docsgpt doctor checks the things that usually break a new setup: whether PostgreSQL answers and its schema matches this version, whether Redis answers, whether a model provider is configured, and whether the port is free. Run it first when something does not start.

   To run the two processes yourself instead, start the ASGI composition under uvicorn. It serves the whole application, hot-reloads on source changes, and matches the production runtime:

   uvicorn docsgpt.asgi:asgi_app --host 0.0.0.0 --port 7091 --reload

   This makes the backend accessible on http://localhost:7091. Production uses gunicorn -k uvicorn_worker.UvicornWorker against the same docsgpt.asgi:asgi_app target.

   A plain Flask run is a faster inner loop (quick startup, the Werkzeug interactive debugger):

   flask --app docsgpt/app.py run --host=0.0.0.0 --port=7091

   But it serves only the WSGI Flask app and omits the native-async routes mounted on the ASGI shell in docsgpt/asgi.py: the /mcp FastMCP endpoint, the chat reconnect reader GET /api/messages/<id>/events, the notification stream GET /api/events, the remote-device command stream GET /api/devices/sessions/<id>/events, and artifact downloads GET /api/artifacts/<id>/download. Under flask run those paths return 404 — chat still works (POST /stream is a Flask route), but live notifications, stream auto-resume, paired devices and artifact downloads don’t. Use flask run only when you don’t need them.

6. Start the Celery Worker (not needed if you used docsgpt dev):

   Open a new terminal window (and activate your virtual environment if you used one). Start the Celery worker to handle background tasks:

   celery -A docsgpt.app.celery worker -l INFO

   This command will start the Celery worker, which processes tasks such as document parsing and vector embedding.

   macOS note: Due to a threading issue, start Celery with the solo pool:

   python -m celery -A docsgpt.app.celery worker -l INFO --pool=solo

Running in Debugger (VSCode):

For easier debugging, you can launch the API and the Celery worker directly from VSCode’s debugger.

• Press Shift + Cmd + D (macOS) or Shift + Windows + D (Windows) to open the Run and Debug view.
• You should see configurations named “API (uvicorn)” and “Celery worker”, and a compound “DocsGPT: Full Stack” that starts them with the frontend. Select one and click the “Start Debugging” button (green play icon).

The API configuration runs the same ASGI app as production, so the routes mounted on the ASGI shell work under the debugger. It deliberately runs without --reload: the reloader restarts the server in a child process, which your breakpoints would not be attached to.

3. Start the Frontend

To run the DocsGPT frontend locally, you’ll need Node.js and npm (Node Package Manager).

Prerequisites:

• Node.js version 16 or higher: Ensure you have Node.js version 16 or greater installed. You can check your Node.js version by running node -v in your terminal. npm is usually bundled with Node.js.

Steps to start the frontend:

1. Navigate to the Frontend Directory:

   In your terminal, change the current directory to the frontend folder within your DocsGPT repository:

   cd frontend

2. Install Global Packages (If Needed):

   If you don’t have husky and vite installed globally, you can install them:

   npm install husky -g
   npm install vite -g

   You can skip this step if you already have these packages installed or prefer to use local installations (though global installation simplifies running the commands in this guide).

3. Install Frontend Dependencies:

   Install the project’s frontend dependencies using npm:

   npm install --include=dev

   This command reads the package.json file in the frontend directory and installs all listed dependencies, including development dependencies.

4. Run the Frontend App:

   Start the frontend development server:

   npm run dev

   This command will start the Vite development server. The frontend application will typically be accessible at http://localhost:5173/ . The terminal will display the exact URL where the frontend is running.

With both the backend and frontend running, you should now have a fully functional DocsGPT development environment. You can access the application in your browser at http://localhost:5173/  and start developing!

Working on two branches at once

Each install keeps its own directory and its own services, so a second branch can run beside the first as long as it gets its own port:

docsgpt dev --port 7092                      # a second checkout, second terminal
docsgpt up --native --dir ~/.docsgpt/review --port 7092   # or a second installed copy

A native install in another directory gets its own service names, so the two never write over each other’s units. docsgpt status --dir ~/.docsgpt/review reports on that one alone.