Deploy with Docker-compose

Prerequisites

1. Basic networking knowledge: ports, firewalls, etc.
2. Docker and Docker Compose basics

Deployment Architecture

Recommended Specs

PgVector Version

Very lightweight, suitable for knowledge base indexes under 50 million.

Milvus Version

Better performance for 100M+ vectors.

View Milvus official recommended specs

Zilliz Cloud Version

Zilliz Cloud is built by the Milvus team — a fully managed SaaS vector database with better performance than Milvus and SLA guarantees. Try Zilliz Cloud.

Since the vector database runs in the cloud, no local resources are needed.

SeekDB Version

SeekDB is a high-performance vector database based on MySQL protocol, fully compatible with OceanBase, supporting efficient vector retrieval.

Preparation

Prepare Docker Environment

# Install Docker
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
systemctl enable --now docker
# Install docker-compose
curl -L https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
# Verify installation
docker -v
docker-compose -v
# If it fails, search online for solutions

brew install orbstack

Start Deployment

1. Get Configuration Files

Method 1: Interactive Script Deployment

Run in Linux/MacOS/Windows WSL. The script guides you through selecting deployment environment, vector database version, IP address, etc.

bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh)

Method 2: Manual Download

If your environment is non-*nix or can't access external networks, manually download docker-compose.yml.

1. Download the docker-compose.yml file:

Download config.json file:

• config.json

2. Modify Environment Variables

For Zilliz version, you also need credentials — see Deploy Zilliz Version: Get Account and Credentials. Other versions can skip to the next step.

3. Open External Ports / Configure Domain

These ports must be accessible:

1. Port 3000 (FastGPT main service)
2. Port 9000 (S3 service)
3. Port 3005 (FastGPT SSE MCP server service)

4. Start Containers

Run in the same directory as docker-compose.yml. Ensure docker-compose version is 2.17+, or automated commands may fail.

# Start containers
docker-compose up -d

5. Access FastGPT

Access FastGPT via the port/domain opened in step 3. Login username is root, password is the DEFAULT_ROOT_PSW set in docker-compose.yml environment variables. Each container restart automatically initializes the root user with password 1234 (matching DEFAULT_ROOT_PSW).

6. Configure Models

• After first login, the system prompts that Language Model and Index Model are not configured and automatically redirects to the model configuration page. At least these two model types are required.
• If the redirect doesn't happen, go to Account - Model Providers to configure models. View tutorial
• Known issue: after first entering the system, the browser tab may become unresponsive. Close the tab and reopen it.

7. Install System Plugins as Needed

Starting from V4.14.0, the fastgpt-plugin image only provides the runtime environment without pre-installed system plugins. All FastGPT systems must manually install system plugins.

• Install via the plugin marketplace — by default it fetches from the public FastGPT Marketplace.
• If your FastGPT can't access the marketplace, visit FastGPT Plugin Marketplace, download .pkg files, and import them via file upload.
• You can also sort tools, set default installations, and manage tags.

FAQ

FastGPT and FastGPT-plugin Version Compatibility

S3 Connection Issues

Check the STORAGE_EXTERNAL_ENDPOINT variable — it must be accessible by both the client and FastGPT service.

Important:

Don't use 127.0.0.1 or localhost or other loopback addresses. Use the host machine's local IP when deploying with Docker, but set it to a static IP; or use a fixed domain name. This prevents 403 errors caused by URL mismatches when signing object storage URLs.

See Object Storage Configuration & Common Issues

Browser Unresponsive After Login

Can't click anything, refresh doesn't help. Close the tab and reopen it.

Mongo Replica Set Auto-Initialization Failed

The latest docker-compose examples have fully automated Mongo replica set initialization. Tested on Ubuntu 20/22, CentOS 7, WSL2, macOS, and Windows. If it still won't start, the CPU likely doesn't support AVX instructions — switch to Mongo 4.x.

To manually initialize the replica set:

1. Create a mongo key in the terminal:

openssl rand -base64 756 > ./mongodb.key
chmod 600 ./mongodb.key
# Change key permissions — some systems use admin, others use root
chown 999:root ./mongodb.key

2. Modify docker-compose.yml to mount the key:

mongo:
  #  image: mongo:5.0.18
  # image: registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.18 # Alibaba Cloud
  container_name: mongo
  ports:
    - 27017:27017
  networks:
    - fastgpt
  command: mongod --keyFile /data/mongodb.key --replSet rs0
  environment:
    # Default username and password, only effective on first run
    - MONGO_INITDB_ROOT_USERNAME=myusername
    - MONGO_INITDB_ROOT_PASSWORD=mypassword
  volumes:
    - ./mongo/data:/data/db
    - ./mongodb.key:/data/mongodb.key

3. Restart services:

docker-compose down
docker-compose up -d

4. Enter the container and initialize the replica set:

# Check if mongo container is running
docker ps
# Enter container
docker exec -it mongo bash

# Connect to database (use your Mongo username and password)
mongo -u myusername -p mypassword --authenticationDatabase admin

# Initialize replica set. For external access, add directConnection=true to the Mongo connection parameters
rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo:27017" }
  ]
})
# Check status — if it shows rs0 status, it's running successfully
rs.status()

How to Change API Address and Key

By default, OneAPI connection address and key are configured. Modify the environment variables in the fastgpt container in docker-compose.yml:

OPENAI_BASE_URL (API endpoint, must include /v1) CHAT_API_KEY (API credentials)

After modifying, restart:

docker-compose down
docker-compose up -d

How to Update Versions?

1. Check the update documentation to confirm the target version — avoid skipping versions.

2. Change the image tag to the target version

3. Run these commands to pull and restart:

   docker-compose pull
   docker-compose up -d

4. Run initialization scripts (if any)

How to Customize Configuration Files?

Modify config.json, then run docker-compose down followed by docker-compose up -d to restart. For details, see Configuration Guide.

How to Check if Custom Config File is Mounted

1. docker logs fastgpt shows logs. After starting the container, the first web request reads the config file — check for success or error messages.
2. docker exec -it fastgpt sh enters the container. Use ls data to check if config.json is mounted. Use cat data/config.json to view it.

Possible reasons it's not working:

1. Incorrect mount directory
2. Invalid config file — logs will show invalid json. The file must be valid JSON.
3. Didn't run docker-compose down then docker-compose up -d after changes. A simple restart doesn't remount files.

How to Check if Environment Variables Loaded

1. docker exec -it fastgpt sh to enter the container.
2. Run env to view all environment variables.

Why Can't I Connect to Local Model Images

docker-compose.yml uses bridge mode to create the fastgpt network. To access other images via 0.0.0.0 or image name, add those images to the same network.

How to Resolve Port Conflicts?

Docker-compose port format: mapped_port:running_port.

In bridge mode, container running ports don't conflict, but mapped ports can. Change the mapped port to a different value.

If container1 needs to connect to container2, use container2:running_port.

(Brush up on Docker basics as needed)

relation "modeldata" does not exist

PG database not connected or initialization failed — check logs. FastGPT initializes tables on each PG connection. Errors will appear in the logs.

1. Check if the database container started normally
2. For non-Docker deployments, manually install the pg vector extension
3. Check fastgpt logs for related errors

Illegal instruction

Possible causes:

1. ARM architecture — use the official Mongo image: mongo:5.0.18
2. CPU doesn't support AVX — switch to mongo4.x. Change the mongo image to: mongo:4.4.29

Operation auth_codes.findOne() buffering timed out after 10000ms

Mongo connection failed — check mongo's running status and logs.

Possible causes:

1. Mongo service didn't start (some CPUs don't support AVX — switch to mongo4.x, find the latest 4.x on Docker Hub, update the image version, and rerun)
2. Database connection environment variables are wrong (username/password, check host and port — for non-container network connections, use public IP and add directConnection=true)
3. Replica set startup failed, causing the container to keep restarting
4. Illegal instruction.... Waiting for MongoDB to start: CPU doesn't support AVX — switch to mongo4.x

First Deployment: Root User Shows Unregistered

Logs will show error messages. Most likely Mongo replica set mode wasn't started.

Can't Export Knowledge Base / Can't Use Voice Input or Playback

SSL certificate not configured — some features require it.

Login Shows Network Error

Caused by service initialization errors triggering a restart.

• 90% of cases: incorrect config file causing JSON parsing errors
• The rest: usually because the vector database can't connect

How to Change Password

Modify DEFAULT_ROOT_PSW in docker-compose.yml and restart — the password auto-updates.

Deploy Zilliz Version: Get Account and Credentials

Open Zilliz Cloud, create an instance, and get the credentials.