FastGPTFastGPT

Local Development Setup

Set up a local FastGPT development and debugging environment with Node.js, pnpm, database dependencies, environment variables, and plugin services.

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:

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:

cd FastGPT/deploy/dev
docker compose up -d
  1. If you cannot pull images, use the China mirror file docker-compose.cn.yml: 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.

4. Initial Configuration

All files below are in the projects/app directory.

# 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. FILE_TOKEN_KEY= is empty in the template but required (at least 6 characters). Set it to a random string in .env.local first, or startup fails with Invalid environment variables. For the other variables, if you haven't modified them in docker-compose.yaml, the defaults in .env.template work as-is. Otherwise, match the values in your yml file. Also update PLUGIN_TOKEN in .env.local to match x-plugin-auth-token in deploy/dev/docker-compose.yml (fastgpt-plugin-dev-token-12345678). For all other variables, the .env.template defaults work when docker-compose.yml is unchanged.

cp .env.template .env.local

2. System Parameters

Starting with 4.15.0, the open-source edition reads environment variables for system parameters; set them in .env.local as needed. See Environment Variables for the full list:

  • VECTOR_MAX_PROCESS: Max vector generation processes (defaults to 10). Adjust based on database and model key concurrency; 10–15 is recommended for a 2c4g server.
  • QA_MAX_PROCESS: Max QA generation processes
  • VLM_MAX_PROCESS: Max image understanding model processes
  • HNSW_EF_SEARCH: HNSW vector search width (defaults to 200) for PG, Milvus, OceanBase, SeekDB, and openGauss. Higher values generally improve recall with increased search latency.

5. Run

See dev.md in the project root. The first build may take longer while dependencies are compiled.

# 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 .
# With China mirrors (any non-empty proxy switches to the ustc apt mirror and npmmirror registry)
docker build -f ./projects/app/Dockerfile -t fastgpt . --build-arg proxy=1

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.

Local Development Troubleshooting

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 MongoDB Compass for MongoDB connection testing and visual management.
  5. Use Navicat or another PostgreSQL client for PostgreSQL connection and management.

postinstall Script Fails

FastGPT runs the postinstall script from the root package.json after pnpm i to generate Chakra UI types and build the SDK and workflow subpackages. If postinstall fails, run the steps manually from the repository root:

pnpm gen:theme-typings && pnpm run build:sdks && pnpm run build:workflow-packages

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

Verify the repository requirements (Node.js 22.23.4+ / 24.22.1+ / 26.12.1+ and pnpm 10.x), check React dependency consistency, and reinstall from the lockfile. Local dev workflow:

  1. Root directory: pnpm i
  2. Copy .env.template -> .env.local and set FILE_TOKEN_KEY
  3. Configure other environment variables in .env.local as needed
  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.

QR code for joining the FastGPT Lark community group

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/ - Application projects: app is the FastGPT main project, alongside services such as code-sandbox, agent-sandbox, agent-sandbox-proxy, volume-manager, mcp_server, and marketplace
  • packages/ - Submodules
    • global - Shared code: functions, type declarations, and constants usable on both frontend and backend
    • service - Server-side code
    • web - Frontend code
    • dal, next, workflow-cli, workflow-core - Other shared subpackages

Domain-Driven Design (DDD)

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

  • core - Core features (Dataset, 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
├── deploy                       // Deployment template sources (docker-compose, k8s, etc.)
├── document                     // Documentation
├── packages                     // Subpackages
│   ├── dal
│   ├── global                   // Frontend/backend shared subpackage
│   ├── next
│   ├── service                  // Backend subpackage
│   ├── web                      // Frontend subpackage
│   ├── workflow-cli
│   └── workflow-core
├── projects
│   ├── app                      // FastGPT main project
│   ├── agent-sandbox            // Agent sandbox image
│   ├── agent-sandbox-proxy      // Agent sandbox proxy
│   ├── code-sandbox             // Code run sandbox
│   ├── fastgpt-ide-agent
│   ├── marketplace              // Plugin marketplace
│   ├── mcp_server               // MCP Server
│   └── volume-manager           // OpenSandbox volume manager
├── sdk                          // SDKs such as otel, sandbox-adapter, and storage
├── scripts                      // Automation scripts
│   ├── icon                     // Icon scripts: pnpm initIcon (write SVG to code), pnpm previewIcon (preview icons)
│   └── postinstall.sh           // ChakraUI custom theme TS type initialization
├── test                         // Tests
├── package.json                 // Top-level monorepo
├── pnpm-lock.yaml
├── pnpm-workspace.yaml          // Monorepo declaration
├── LICENSE
├── README.md
├── README_en.md
├── README_ja.md
└── dev.md
Edit on GitHub

Last updated