DocsGPT/docs/content/Deploying/Development-Environment.mdx

---
title: Setting Up a Development Environment
description: Guide to setting up a development environment for DocsGPT, including backend and frontend setup.
---

import { Callout } from 'nextra/components'

# 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 along with a one-shot `postgres-init` migrator that applies the Alembic schema.

You can find the `docker-compose-dev.yaml` file [here](https://github.com/arc53/DocsGPT/blob/main/deployment/docker-compose-dev.yaml).

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

    ```bash
    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. The `postgres-init` service runs once against the fresh database and then exits.

<Callout type="info" emoji="ℹ️">
  MongoDB is no longer required for a default DocsGPT install. If you
  specifically want to use MongoDB Atlas as the vector store
  (`VECTOR_STORE=mongodb`), start it on the side via
  `deployment/docker-compose.mongo.yaml`. For migrating an existing
  Mongo-based install to Postgres, see
  [PostgreSQL for User Data](/Deploying/Postgres-Migration).
</Callout>

## 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](/Deploying/DocsGPT-Settings).

    *   **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 [`application/core/settings.py`](https://github.com/arc53/DocsGPT/blob/main/application/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:**

        ```bash
        python -m venv venv
        . venv/bin/activate
        ```

    *   **Windows:**

        ```bash
        python -m venv venv
         venv/Scripts/activate
        ```

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

    ```bash
    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](https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip), unzip it, and place the extracted folder in `models/`.

4.  **Install Backend Dependencies:**

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

    ```bash
    pip install -r application/requirements.txt
    ```

5.  **Run the Flask App:**

    Start the Flask backend application:

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

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

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

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

*   Press <kbd>Shift</kbd> + <kbd>Cmd</kbd> + <kbd>D</kbd> (macOS) or <kbd>Shift</kbd> + <kbd>Windows</kbd> + <kbd>D</kbd> (Windows) to open the Run and Debug view.
*   You should see configurations named "Flask" and "Celery". Select the desired configuration and click the "Start Debugging" button (green play icon).

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

    ```bash
    cd frontend
    ```

2.  **Install Global Packages (If Needed):**

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

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

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

    ```bash
    npm run dev
    ```

    This command will start the Vite development server. The frontend application will typically be accessible at [http://localhost:5173/](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/](http://localhost:5173/) and start developing!