Local Development Setup

This guide covers how to set up your development environment to build and test FastGPT.

Prerequisites

Install and configure these dependencies on your machine to build FastGPT:

Git
Docker
Node.js v20.14.0 (match this version closely; use nvm to manage Node versions)
pnpm recommended version 9.4.0 (current official dev environment)

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

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.

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.

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.

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

# 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

Make sure your code is forked from the FastGPT repository.
Keep commits small and focused — each should address one issue.
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

For remote databases, check if the port is open.
For local databases, try changing host to localhost or 127.0.0.1.
For local connections to remote MongoDB, add directConnection=true to connect to replica sets.
Use mongocompass for MongoDB connection testing and visual management.
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:

Root directory: pnpm i
Copy config.json -> config.local.json
Copy .env.template -> .env.local
cd projects/app
pnpm dev

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.)

Code Structure Details

.
├── .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

Prerequisites