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: Deploy with an AI Agent

Copy the following content to your Coding Agent:

Refer to https://doc.fastgpt.cn/deploy/SKILL.md and deploy FastGPT with Docker for me.

Method 2: 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)

The script automatically:

• Downloads or copies docker-compose.yml.
• Guides you through selecting externally accessible S3 and MCP addresses, then writes them into the config files.
• Generates a random root login password, service tokens, app keys, and component passwords, then writes them into docker-compose.yml.
• Detects the host Docker socket path and updates the mount path in docker-compose.yml when needed.

After the script finishes, the terminal prints the generated root login password. Keep the generated docker-compose.yml safe. For future upgrades, start from this file so you do not lose the generated passwords and keys.

To use an existing local docker-compose.yml file, for example when testing a version that has not been published to the docs site yet, choose 本地 docker-compose.yml (local docker-compose.yml) in the deployment version step and enter the local file path. You can also pass the path with an environment variable:

FASTGPT_LOCAL_COMPOSE_PATH=/path/to/docker-compose.yml bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh)

Method 3: Manual Download

If you need to pin deployment to a specific docker-compose.yml file, we recommend downloading both docker-compose.yml and install.sh, then using the script's local compose mode to generate the final config. This keeps the script's random credential generation, S3/MCP address updates, and Docker socket detection.

1. Download the required docker-compose.yml file to the server, for example:

curl -fsSL https://doc.fastgpt.cn/deploy/docker/v4.15/cn/docker-compose.pg.yml -o docker-compose.source.yml

2. Download install.sh to the server:

curl -fsSL https://doc.fastgpt.cn/deploy/install.sh -o install.sh

3. Run install.sh with the local compose file to generate the final deployment config:

FASTGPT_LOCAL_COMPOSE_PATH=./docker-compose.source.yml bash install.sh

The script copies this compose file to the final docker-compose.yml, then generates login passwords and credentials, and writes the S3/MCP addresses. After generation, log in with the root password printed in the terminal.

For a fully offline environment, prepare docker-compose.yml and install.sh in advance. If the script cannot run, manually update DEFAULT_ROOT_PSW, service tokens, database passwords, and S3/MCP addresses.

Deploy with a Custom Image Registry

If you use an internal Harbor, private registry, or image mirror, download docker-compose.yml first, replace all image: values with your own registry addresses, and then use local compose mode:

FASTGPT_LOCAL_COMPOSE_PATH=./docker-compose.yml bash install.sh

If Agent/Skill Sandbox is enabled, deploy fastgpt-agent-sandbox-proxy separately and also replace AGENT_SANDBOX_SEALOS_IMAGE or AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO so the sandbox provider can pull the fastgpt-agent-sandbox image. The v4.15.0 default deployment file does not include fastgpt-agent-sandbox-proxy or start OpenSandbox by default. See the V4.15.0 upgrade notes for sandbox provider setup.

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 3003 (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.

If you deploy with the interactive script, it randomly generates DEFAULT_ROOT_PSW and prints the login password when it finishes. If you deploy manually, change the default password in docker-compose.yml before starting the service. Each container restart automatically updates the root user's password based on 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 up -d

4. Run initialization scripts (if any)

How to Customize Environment Variables?

Edit the environment section of fastgpt-app in docker-compose.yml, then run docker compose up -d to restart the container. For details, see Environment Variables.

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.