ContextQMD
Back to Fastgpt

Local Development Setup

document/content/docs/self-host/dev.en.mdx

4.14.188.1 KB
Original Source

import { Alert } from '@/components/docs/Alert'; import FastGPTLink from '@/components/docs/linkFastGPT';

This guide covers how to set up your development environment to build and test <FastGPTLink>FastGPT</FastGPTLink>.

Prerequisites

Install and configure these dependencies on your machine to build <FastGPTLink>FastGPT</FastGPTLink>:

We recommend developing on *nix environments (Linux, macOS, Windows WSL).

Local Development

1. Fork the FastGPT Repository

Fork the FastGPT repository.

2. Clone the Repository

Clone your forked repository from GitHub:

git clone [email protected]:<your_github_username>/FastGPT.git

3. Start the Development Environment with Docker

If you're already running FastGPT locally via Docker, stop it first to avoid port conflicts.

Navigate to FastGPT/deploy/dev and run docker compose up -d to start FastGPT's dependencies:

bash
cd FastGPT/deploy/dev
docker compose up -d
<Alert context="warning"> 1. If you can't pull images, use the China mirror version: `docker compose -f docker-compose.cn.yml up -d` 2. For MongoDB, add the `directConnection=true` parameter to your connection string to connect to the replica set. </Alert>

4. Initial Configuration

All files below are in the projects/app directory.

bash
# Make sure you're in projects/app
pwd
# Should output /xxxx/xxxx/xxx/FastGPT/projects/app

1. Environment Variables

Copy .env.template to create .env.local in the same directory. Only changes in .env.local take effect. See .env.template for variable descriptions. If you haven't modified variables in docker-compose.yaml, the defaults in .env.template work as-is. Otherwise, match the values in your yml file.

bash
cp .env.template .env.local

2. config.json Configuration File

Copy data/config.json to create data/config.local.json. For detailed parameters, see Configuration Guide.

bash
cp data/config.json data/config.local.json

This file usually doesn't need changes. Key systemEnv parameters:

  • vectorMaxProcess: Max vector generation processes. Depends on database and key concurrency — for a 2c4g server, set to 10–15.
  • qaMaxProcess: Max QA generation processes
  • vlmMaxProcess: Max image understanding model processes
  • hnswEfSearch: Vector search parameter (PG and OB only). Higher values = better accuracy but slower speed.

5. Run

See dev.md in the project root. The first compile may take a while — be patient.

bash
# Run from the code root directory to install all dependencies
# If isolate-vm installation fails, see: https://github.com/laverdet/isolated-vm?tab=readme-ov-file#requirements
pwd # Should be in the code root directory
pnpm i
cd projects/app
pnpm dev

Next.js runs on port 3000 by default. Visit http://localhost:3000

6. Build

We recommend using Docker for builds.

bash
# Without proxy
docker build -f ./projects/app/Dockerfile -t fastgpt . --build-arg name=app
# With Taobao proxy
docker build -f ./projects/app/Dockerfile -t fastgpt. --build-arg name=app --build-arg proxy=taobao

Without Docker, you'd need to manually execute all the run-stage commands from the Dockerfile (not recommended).

Contributing to the Open Source Repository

  1. Make sure your code is forked from the FastGPT repository.
  2. Keep commits small and focused — each should address one issue.
  3. Submit a PR to FastGPT's main branch. The FastGPT team and community will review it with you.

If you run into issues like merge conflicts, check GitHub's pull request tutorial. Once your PR is merged, you'll be listed in the contributors table.

QA

System Time Anomaly

If your default timezone is Asia/Shanghai, system time may be incorrect in non-Linux environments. For local development, change your timezone to UTC (+0).

Can't Connect to Local Database

  1. For remote databases, check if the port is open.
  2. For local databases, try changing host to localhost or 127.0.0.1.
  3. For local connections to remote MongoDB, add directConnection=true to connect to replica sets.
  4. Use mongocompass for MongoDB connection testing and visual management.
  5. Use navicat for PostgreSQL connection and management.

sh ./scripts/postinstall.sh Permission Denied

FastGPT runs a postinstall script after pnpm i to auto-generate ChakraUI types. If you get a permission error, run chmod -R +x ./scripts/ first, then pnpm i.

If that doesn't work, manually execute the contents of ./scripts/postinstall.sh. On Windows, use git bash to add execute permissions and run the script.

TypeError: Cannot read properties of null (reading 'useMemo')

Delete all node_modules and reinstall with Node 18 — newer Node versions may have issues. Local dev workflow:

  1. Root directory: pnpm i
  2. Copy config.json -> config.local.json
  3. Copy .env.template -> .env.local
  4. cd projects/app
  5. pnpm dev

Error response from daemon: error while creating mount source path 'XXX': mkdir XXX: file exists

This may be caused by leftover files from a previous container stop. Make sure all related containers are stopped, then manually delete the files or restart Docker.

Join the Community

Having trouble? Join the Lark group to connect with developers and users.

Code Structure

Next.js

FastGPT uses Next.js page routing. To separate frontend and backend code, directories are split into global, service, and web subdirectories for shared, backend-only, and frontend-only code respectively.

Monorepo

FastGPT uses pnpm workspace for its monorepo structure, with two main parts:

  • projects/app - FastGPT main project
  • packages/ - Submodules
    • global - Shared code: functions, type declarations, and constants usable on both frontend and backend
    • service - Server-side code
    • web - Frontend code
    • plugin - Custom workflow plugin code

Domain-Driven Design (DDD)

FastGPT's code modules follow DDD principles, divided into these domains:

  • core - Core features (knowledge base, workflow, app, conversation)
  • support - Supporting features (user system, billing, authentication, etc.)
  • common - Base features (log management, file I/O, etc.)
<details> <summary>Code Structure Details</summary> 
.
├── .github                      // GitHub config
├── .husky                       // Formatting config
├── document                      // Documentation
├── files                        // External files, e.g., docker-compose, helm
├── packages                     // Subpackages
│   ├── global                   // Frontend/backend shared subpackage
│   ├── plugins                  // Workflow plugins (for custom packages)
│   ├── service                  // Backend subpackage
│   └── web                      // Frontend subpackage
├── projects
│   └── app                      // FastGPT main project
├── python                       // Model code, unrelated to FastGPT itself
└── scripts                      // Automation scripts
    ├── icon                     // Icon scripts: pnpm initIcon (write SVG to code), pnpm previewIcon (preview icons)
    └── postinstall.sh           // ChakraUI custom theme TS type initialization
├── package.json                 // Top-level monorepo
├── pnpm-lock.yaml
├── pnpm-workspace.yaml          // Monorepo declaration
├── Dockerfile
├── LICENSE
├── README.md
├── README_en.md
├── README_ja.md
├── dev.md
</details>