document/content/docs/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)
If your environment is non-*nix or can't access external networks, manually download docker-compose.yml.
docker-compose.yml file:config.json file:Download config.json file:
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 --profile prepull pull opensandbox-agent-sandbox-image opensandbox-execd-image opensandbox-egress-image && dockercompose 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.
Each container restart automatically initializes the root user with password 1234 (matching 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 |
|---|---|
| 0.6.x | >= 4.14.11 |
| 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)
Modify config.json, then run docker compose down followed by docker compose up -d to restart. For details, see Configuration Guide.
docker logs fastgpt shows logs. After starting the container, the first web request reads the config file — check for success or error messages.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:
invalid json. The file must be valid JSON.docker compose down then docker compose up -d after changes. A simple restart doesn't remount files.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.