document/content/self-host/deploy/docker.en.mdx
import { Alert } from '@/components/docs/Alert';
Very lightweight, suitable for knowledge base indexes under 50 million.
| Environment | Minimum (Single Node) | Recommended |
|---|---|---|
| Testing (reduce compute processes) | 2c4g | 2c8g |
| 1M vector groups | 4c8g 50GB | 4c16g 50GB |
| 5M vector groups | 8c32g 200GB | 16c64g 200GB |
Better performance for 100M+ vectors.
View Milvus official recommended specs
| Environment | Minimum (Single Node) | Recommended |
|---|---|---|
| Testing | 2c8g | 4c16g |
| 1M vector groups | Not tested | |
| 5M vector groups |
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 is a high-performance vector database based on MySQL protocol, fully compatible with OceanBase, supporting efficient vector retrieval.
| Environment | Minimum (Single Node) | Recommended |
|---|---|---|
| Testing (reduce compute processes) | 2c4g | 2c8g |
| 1M vector groups | 4c8g 50GB | 4c16g 50GB |
| 5M vector groups | 8c32g 200GB | 16c64g 200GB |
SeekDB uses MySQL protocol, fully compatible with OceanBase:
<Tabs items={['Linux','MacOS','Windows']}> <Tab value="Linux">
# 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
Or download the installer directly.
</Tab> <Tab value="Windows"> We recommend storing source code and data in the Linux filesystem when binding to Linux containers, not the Windows filesystem.You can install Docker Desktop with WSL 2 backend on Windows.
Or install the command-line version of Docker directly in WSL 2.
</Tab> </Tabs>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:
docker-compose.yml, and downloads config.json.root login password, service tokens, app keys, and component passwords, then writes them into docker-compose.yml.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)
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.
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
install.sh to the server:curl -fsSL https://doc.fastgpt.cn/deploy/install.sh -o install.sh
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 downloads config.json, 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, config.json, and install.sh in advance. If the script cannot download config.json, manually update DEFAULT_ROOT_PSW, service tokens, database passwords, and S3/MCP addresses.
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.
For Zilliz version, you also need credentials — see Deploy Zilliz Version: Get Account and Credentials. Other versions can skip to the next step.
These ports must be accessible:
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
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.
Language Model and Index Model are not configured and automatically redirects to the model configuration page. At least these two model types are required.Account - Model Providers to configure models. View tutorialStarting 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.
| FastGPT-plugin Version | FastGPT Main Service |
|---|---|
| 1.x | 4.15.x |
| 0.6.x | >= 4.14.11, < 4.15.0 |
| 0.5.x | >= 4.14.6, < 4.14.11 |
| < 0.5.0 | < 4.14.6 |
Check the STORAGE_EXTERNAL_ENDPOINT variable — it must be accessible by both the client and FastGPT service.
Important:
Don't use
127.0.0.1orlocalhostor 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.
Can't click anything, refresh doesn't help. Close the tab and reopen it.
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:
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
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
docker compose down
docker compose up -d
# 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()
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
Check the update documentation to confirm the target version — avoid skipping versions.
Change the image tag to the target version
Run these commands to pull and restart:
docker compose up -d
Run initialization scripts (if any)
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.
docker exec -it fastgpt sh to enter the container.env to view all environment variables.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.
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)
PG database not connected or initialization failed — check logs. FastGPT initializes tables on each PG connection. Errors will appear in the logs.
Possible causes:
auth_codes.findOne() buffering timed out after 10000msMongo connection failed — check mongo's running status and logs.
Possible causes:
Illegal instruction.... Waiting for MongoDB to start: CPU doesn't support AVX — switch to mongo4.xLogs will show error messages. Most likely Mongo replica set mode wasn't started.
SSL certificate not configured — some features require it.
Caused by service initialization errors triggering a restart.
Modify DEFAULT_ROOT_PSW in docker-compose.yml and restart — the password auto-updates.
Open Zilliz Cloud, create an instance, and get the credentials.
<Alert icon="🤖" context="success">MILVUS_ADDRESS and MILVUS_TOKEN to match Zilliz's Public Endpoint and Api key. Remember to add your IP to the whitelist.