From 8c219540494ab02ef464cd2e6ab68d06af487972 Mon Sep 17 00:00:00 2001 From: Alex Date: Sat, 25 Jan 2025 20:36:10 +0000 Subject: [PATCH] feat: improved docs --- CONTRIBUTING.md | 5 +- README.md | 103 ++++-------------- .../Deploying/Develepment-Environment.md | 78 +++++++++++++ docs/pages/Deploying/Quickstart.md | 59 +++++----- docs/pages/Deploying/_meta.json | 4 + 5 files changed, 132 insertions(+), 117 deletions(-) create mode 100644 docs/pages/Deploying/Develepment-Environment.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b0567e4..8e41b9ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,15 +36,14 @@ Tech Stack Overview: ### 🌐 If you are looking to contribute to frontend (⚛️React, Vite): -- The current frontend is being migrated from [`/application`](https://github.com/arc53/DocsGPT/tree/main/application) to [`/frontend`](https://github.com/arc53/DocsGPT/tree/main/frontend) with a new design, so please contribute to the new one. -- Check out this [milestone](https://github.com/arc53/DocsGPT/milestone/1) and its issues. + - The updated Figma design can be found [here](https://www.figma.com/file/OXLtrl1EAy885to6S69554/DocsGPT?node-id=0%3A1&t=hjWVuxRg9yi5YkJ9-1). Please try to follow the guidelines. ### 🖥 If you are looking to contribute to Backend (🐍 Python): -- Review our issues and contribute to [`/application`](https://github.com/arc53/DocsGPT/tree/main/application) or [`/scripts`](https://github.com/arc53/DocsGPT/tree/main/scripts) (please disregard old [`ingest_rst.py`](https://github.com/arc53/DocsGPT/blob/main/scripts/old/ingest_rst.py) [`ingest_rst_sphinx.py`](https://github.com/arc53/DocsGPT/blob/main/scripts/old/ingest_rst_sphinx.py) files; these will be deprecated soon). +- Review our issues and contribute to [`/application`](https://github.com/arc53/DocsGPT/tree/main/application) - All new code should be covered with unit tests ([pytest](https://github.com/pytest-dev/pytest)). Please find tests under [`/tests`](https://github.com/arc53/DocsGPT/tree/main/tests) folder. - Before submitting your Pull Request, ensure it can be queried after ingesting some test data. diff --git a/README.md b/README.md index ef66bc4d..d550b639 100644 --- a/README.md +++ b/README.md @@ -68,107 +68,46 @@ We're eager to provide personalized assistance when deploying your DocsGPT to a > [!Note] > Make sure you have [Docker](https://docs.docker.com/engine/install/) installed + +1. Clone the repository and run the following command: + ```bash + git clone https://github.com/arc53/DocsGPT.git + cd DocsGPT + ``` + On Mac OS or Linux, write: -`./setup.sh` + +2. Run the following command: + ```bash + ./setup.sh + ``` It will install all the dependencies and allow you to download the local model, use OpenAI or use our LLM API. Otherwise, refer to this Guide for Windows: -1. Download and open this repository with `git clone https://github.com/arc53/DocsGPT.git` -2. Create a `.env` file in your root directory and set the env variables and `VITE_API_STREAMING` to true or false, depending on whether you want streaming answers or not. +On windows: + +2. Create a `.env` file in your root directory and set the env variables. It should look like this inside: ``` LLM_NAME=[docsgpt or openai or others] - VITE_API_STREAMING=true API_KEY=[if LLM_NAME is openai] ``` - See optional environment variables in the [/.env-template](https://github.com/arc53/DocsGPT/blob/main/.env-template) and [/application/.env_sample](https://github.com/arc53/DocsGPT/blob/main/application/.env_sample) files. + See optional environment variables in the [/application/.env_sample](https://github.com/arc53/DocsGPT/blob/main/application/.env_sample) file. -3. Run [./run-with-docker-compose.sh](https://github.com/arc53/DocsGPT/blob/main/run-with-docker-compose.sh). +3. Run the following command: + + ```bash + docker-compose up + ``` 4. Navigate to http://localhost:5173/. To stop, just run `Ctrl + C`. -## Development Environments - -### Spin up Mongo and Redis - -For development, only two containers are used from [docker-compose.yaml](https://github.com/arc53/DocsGPT/blob/main/docker-compose.yaml) (by deleting all services except for Redis and Mongo). -See file [docker-compose-dev.yaml](./docker-compose-dev.yaml). - -Run - -``` -docker compose -f docker-compose-dev.yaml build -docker compose -f docker-compose-dev.yaml up -d -``` - -### Run the Backend - -> [!Note] -> Make sure you have Python 3.12 installed. - -1. Export required environment variables or prepare a `.env` file in the project folder: - - Copy [.env-template](https://github.com/arc53/DocsGPT/blob/main/application/.env-template) and create `.env`. - -(check out [`application/core/settings.py`](application/core/settings.py) if you want to see more config options.) - -2. (optional) Create a Python virtual environment: - You can follow the [Python official documentation](https://docs.python.org/3/tutorial/venv.html) for virtual environments. - -a) On Mac OS and Linux - -```commandline -python -m venv venv -. venv/bin/activate -``` - -b) On Windows - -```commandline -python -m venv venv - venv/Scripts/activate -``` - -3. Download embedding model and save it in the `model/` folder: -You can use the script below, or download it manually from [here](https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip), unzip it and save it in the `model/` folder. - -```commandline -wget https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip -unzip mpnet-base-v2.zip -d model -rm mpnet-base-v2.zip -``` - -4. Install dependencies for the backend: - -```commandline -pip install -r application/requirements.txt -``` - -5. Run the app using `flask --app application/app.py run --host=0.0.0.0 --port=7091`. -6. Start worker with `celery -A application.app.celery worker -l INFO`. - -### Start Frontend - -> [!Note] -> Make sure you have Node version 16 or higher. - -1. Navigate to the [/frontend](https://github.com/arc53/DocsGPT/tree/main/frontend) folder. -2. Install the required packages `husky` and `vite` (ignore if already installed). - -```commandline -npm install husky -g -npm install vite -g -``` - -3. Install dependencies by running `npm install --include=dev`. -4. Run the app using `npm run dev`. - - ## Contributing Please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file for information about how to get involved. We welcome issues, questions, and pull requests. diff --git a/docs/pages/Deploying/Develepment-Environment.md b/docs/pages/Deploying/Develepment-Environment.md new file mode 100644 index 00000000..bf489fb8 --- /dev/null +++ b/docs/pages/Deploying/Develepment-Environment.md @@ -0,0 +1,78 @@ +## Development Environments + +### Spin up Mongo and Redis + +For development, only two containers are used from [docker-compose.yaml](https://github.com/arc53/DocsGPT/blob/main/docker-compose.yaml) (by deleting all services except for Redis and Mongo). +See file [docker-compose-dev.yaml](https://github.com/arc53/DocsGPT/blob/main/docker-compose-dev.yaml). + +Run + +``` +docker compose -f docker-compose-dev.yaml build +docker compose -f docker-compose-dev.yaml up -d +``` + +### Run the Backend + +> [!Note] +> Make sure you have Python 3.12 installed. + +1. Export required environment variables or prepare a `.env` file in the project folder: + - Copy [.env-template](https://github.com/arc53/DocsGPT/blob/main/application/.env-template) and create `.env`. + +(check out [`application/core/settings.py`](application/core/settings.py) if you want to see more config options.) + +2. (optional) Create a Python virtual environment: + You can follow the [Python official documentation](https://docs.python.org/3/tutorial/venv.html) for virtual environments. + +a) On Mac OS and Linux + +```commandline +python -m venv venv +. venv/bin/activate +``` + +b) On Windows + +```commandline +python -m venv venv + venv/Scripts/activate +``` + +3. Download embedding model and save it in the `model/` folder: +You can use the script below, or download it manually from [here](https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip), unzip it and save it in the `model/` folder. + +```commandline +wget https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip +unzip mpnet-base-v2.zip -d model +rm mpnet-base-v2.zip +``` + +4. Install dependencies for the backend: + +```commandline +pip install -r application/requirements.txt +``` + +5. Run the app using `flask --app application/app.py run --host=0.0.0.0 --port=7091`. +6. Start worker with `celery -A application.app.celery worker -l INFO`. + +> [!Note] +> You can also launch the in a debugger mode in vscode by accessing SHIFT + CMD + D or SHIFT + Windows + D on windows and selecting Flask or Celery. + + +### Start Frontend + +> [!Note] +> Make sure you have Node version 16 or higher. + +1. Navigate to the [/frontend](https://github.com/arc53/DocsGPT/tree/main/frontend) folder. +2. Install the required packages `husky` and `vite` (ignore if already installed). + +```commandline +npm install husky -g +npm install vite -g +``` + +3. Install dependencies by running `npm install --include=dev`. +4. Run the app using `npm run dev`. \ No newline at end of file diff --git a/docs/pages/Deploying/Quickstart.md b/docs/pages/Deploying/Quickstart.md index a2bdc706..671d242c 100644 --- a/docs/pages/Deploying/Quickstart.md +++ b/docs/pages/Deploying/Quickstart.md @@ -15,11 +15,21 @@ If you prefer to follow manual steps, refer to this guide: 1. Open and download this repository with ```bash git clone https://github.com/arc53/DocsGPT.git + cd DocsGPT ``` -2. Create a `.env` file in your root directory and set your `API_KEY` with your [OpenAI API key](https://platform.openai.com/account/api-keys). (optional in case you want to use OpenAI) +2. Create a `.env` file in your root directory and set the env variables. + It should look like this inside: + + ``` + LLM_NAME=[docsgpt or openai or others] + API_KEY=[if LLM_NAME is openai] + ``` + + See optional environment variables in the [/application/.env_sample](https://github.com/arc53/DocsGPT/blob/main/application/.env_sample) file. + 3. Run the following commands: ```bash - docker-compose build && docker-compose up + docker compose up ``` 4. Navigate to http://localhost:5173/. @@ -27,43 +37,28 @@ To stop, simply press **Ctrl + C**. **For WINDOWS:** -To run the setup on Windows, you have two options: using the Windows Subsystem for Linux (WSL) or using Git Bash or Command Prompt. - -**Option 1: Using Windows Subsystem for Linux (WSL):** - -1. Install WSL if you haven't already. You can follow the official Microsoft documentation for installation: (https://learn.microsoft.com/en-us/windows/wsl/install). -2. After setting up WSL, open the WSL terminal. -3. Clone the repository and create the `.env` file: +1. Open and download this repository with ```bash git clone https://github.com/arc53/DocsGPT.git cd DocsGPT - echo "API_KEY=Yourkey" > .env - echo "VITE_API_STREAMING=true" >> .env ``` -4. Run the following command to start the setup with Docker Compose: - ```bash - ./run-with-docker-compose.sh - ``` -6. Open your web browser and navigate to http://localhost:5173/. -7. To stop the setup, just press **Ctrl + C** in the WSL terminal -**Option 2: Using Git Bash or Command Prompt (CMD):** +2. Create a `.env` file in your root directory and set the env variables. + It should look like this inside: -1. Install Git for Windows if you haven't already. Download it from the official website: (https://gitforwindows.org/). -2. Open Git Bash or Command Prompt. -3. Clone the repository and create the `.env` file: - ```bash - git clone https://github.com/arc53/DocsGPT.git - cd DocsGPT - echo "API_KEY=Yourkey" > .env - echo "VITE_API_STREAMING=true" >> .env ``` -4. Run the following command to start the setup with Docker Compose: - ```bash - ./run-with-docker-compose.sh + LLM_NAME=[docsgpt or openai or others] + API_KEY=[if LLM_NAME is openai] ``` -5. Open your web browser and navigate to http://localhost:5173/. -6. To stop the setup, just press **Ctrl + C** in the Git Bash or Command Prompt terminal. -These steps should help you set up and run the project on Windows using either WSL or Git Bash/Command Prompt. + See optional environment variables in the [/application/.env_sample](https://github.com/arc53/DocsGPT/blob/main/application/.env_sample) file. + +3. Run the following command: + + ```bash + docker-compose up + ``` +4. Navigate to http://localhost:5173/. +5. To stop the setup, just press **Ctrl + C** in the WSL terminal + **Important:** Ensure that Docker is installed and properly configured on your Windows system for these steps to work. diff --git a/docs/pages/Deploying/_meta.json b/docs/pages/Deploying/_meta.json index 64cd77db..d01e1f67 100644 --- a/docs/pages/Deploying/_meta.json +++ b/docs/pages/Deploying/_meta.json @@ -7,6 +7,10 @@ "title": "⚡️Quickstart", "href": "/Deploying/Quickstart" }, + "Development-Environment": { + "title": "🛠️Development Environment", + "href": "/Deploying/Development-Environment" + }, "Railway-Deploying": { "title": "🚂Deploying on Railway", "href": "/Deploying/Railway-Deploying"