docs/content/Deploying/Development-Environment.mdx
import { Callout } from 'nextra/components'
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.
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:
Navigate to the root directory of your DocsGPT repository in your terminal.
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.
To run the DocsGPT backend locally, you'll need to set up a Python environment and install the necessary dependencies.
Prerequisites:
python --version or python3 --version in your terminal.Steps to run the backend:
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):
.env in the root directory of your DocsGPT project..env file to adjust settings as needed. You can find a comprehensive list of configurable options in application/core/settings.py.Option 2: Exporting Environment Variables:
.env file is generally more organized for development.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
Download Embedding Model:
The backend requires an embedding model. Download the mpnet-base-v2 model and place it in the models/ directory within the project root. You can use the following script:
wget https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip
unzip mpnet-base-v2.zip -d model
rm mpnet-base-v2.zip
Alternatively, you can manually download the zip file from here, unzip it, and place the extracted folder in models/.
Install Backend Dependencies:
Navigate to the root of your DocsGPT repository and install the required Python packages:
pip install -r application/requirements.txt
Run the Flask App:
Start the Flask backend application:
flask --app application/app.py run --host=0.0.0.0 --port=7091
This command will launch the backend server, making it accessible on http://localhost:7091. It's the fastest inner-loop option for day-to-day development — the Werkzeug interactive debugger still works and it hot-reloads on source changes. It serves the Flask routes only.
If you need to exercise the full ASGI stack — the /mcp endpoint (FastMCP server), or to match the production runtime — run the ASGI composition under uvicorn instead:
uvicorn application.asgi:asgi_app --host 0.0.0.0 --port 7091 --reload
Production uses gunicorn -k uvicorn_worker.UvicornWorker against the same application.asgi:asgi_app target.
Start the Celery Worker:
Open a new terminal window (and activate your virtual environment if you used one). Start the Celery worker to handle background tasks:
celery -A application.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 application.app.celery worker -l INFO --pool=solo
Running in Debugger (VSCode):
For easier debugging, you can launch the Flask app and Celery worker directly from VSCode's debugger.
To run the DocsGPT frontend locally, you'll need Node.js and npm (Node Package Manager).
Prerequisites:
node -v in your terminal. npm is usually bundled with Node.js.Steps to start the frontend:
Navigate to the Frontend Directory:
In your terminal, change the current directory to the frontend folder within your DocsGPT repository:
cd frontend
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).
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.
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!