Deploy with Docker Compose

FastGPT supports single-host self-hosted deployment via Docker Compose on Linux, macOS, and Windows, provisioning the core web app, plugin runtime, AI Proxy model gateway, MongoDB, RustFS object storage, and your choice of pgvector, Milvus, Zilliz, OceanBase, SeekDB, or OpenGauss vector database.

Prerequisites

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

Deployment Architecture

Recommended Specs

Vector Database Selection Matrix

PgVector Version

The following are historical sizing estimates. Actual requirements depend on vector dimensions, index settings, document size, concurrency, and other services on the host. Benchmark representative data and reserve capacity for backups and growth.

Milvus Version

Use Milvus when your deployment needs a separately managed vector-search service. Validate capacity and performance with a representative benchmark.

Milvus must be version 2.5.16 or later. FastGPT uses BM25 full-text search in modeldata_v2 with Milvus; startup rejects older Milvus versions.

View Milvus official recommended specs

Zilliz Cloud Version

Zilliz Cloud provides a managed vector database. Capacity, connectivity, SLA, and pricing depend on the selected plan.

The vector service runs in the cloud. FastGPT, MongoDB, object storage, and other local components still need resources.

SeekDB Version

SeekDB uses the MySQL protocol and has a FastGPT vector-store adapter. Treat the table as sizing estimates; verify the database version, model dimensions, and actual workload.

Preparation

Prepare Docker Environment

# Install Docker (includes the Docker Compose V2 plugin)
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
systemctl enable --now docker
# Verify installation
docker -v
docker compose version

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.io/deploy/SKILL.md and deploy FastGPT with Docker for me.

Method 2: Interactive Script Deployment

Run in Linux/MacOS/Windows WSL. The script prompts for the deployment version, image registry, vector database, and whether to generate credentials automatically, then asks for the FastGPT access URL, the Sandbox WebSocket / preview URLs, and host ports before the final confirmation.

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

If the documentation site uses a custom domain, an internal domain, or a local address, set FASTGPT_DEPLOY_BASE_URL to choose the download source. You can provide either the site root or a URL ending in /deploy; the script downloads docker-compose.yml from that source, as in the command above. When an older compose file still mounts config.json, the script downloads that file too.

Set FASTGPT_NON_INTERACTIVE=true to run in non-interactive mode. The script skips the prompts and reads options from variables such as FASTGPT_DEPLOY_VERSION, FASTGPT_REGION, FASTGPT_VECTOR, and FASTGPT_AUTO_GENERATE_CREDENTIALS; unset options default to main, cn, pg, and automatic credential generation. If the script cannot detect the image version, set FASTGPT_IMAGE_TAG or FASTGPT_ROOT_ACTIVATION.

Non-interactive mode also requires FASTGPT_FE_DOMAIN, the full URL users use to access FastGPT, such as https://fastgpt.example.com. Versions with Agent/Skill Sandbox also require FASTGPT_SANDBOX_PROXY_URL, the Sandbox WebSocket URL, such as wss://sandbox-proxy.example.com; Versions 4.16 and later also require FASTGPT_SANDBOX_PREVIEW_PROXY_URL for the HTTP preview URL.

Access URLs and host ports are configured independently. For direct access, set FASTGPT_PORT for the FastGPT host port (default 3000) and FASTGPT_SANDBOX_PROXY_PORT for the Sandbox Proxy host port (default 3006); the container ports remain 3000 and 1006. With a reverse proxy, public ports in FASTGPT_FE_DOMAIN, FASTGPT_SANDBOX_PROXY_URL, and the preview URL (for example, 443) are not treated as host ports, so the script keeps the default Compose mappings.

The script automatically performs the following actions:

• Downloads docker-compose.yml.
• When deploying v4.14, or when the local compose file contains STORAGE_EXTERNAL_ENDPOINT, prompts for the externally accessible S3 address and writes it into the config files.
• Generates random service tokens, app keys, and component passwords, then writes them into docker-compose.yml. For v4.17.2 and earlier, it also generates a random root login password.
• 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 root login details: for v4.17.3 and later, the initial password is fixed at 123456 and you set a new password through first-login account activation; for earlier versions, it prints the randomly generated 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 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.io/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 address updates, and Docker socket detection.

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

curl -fsSL https://doc.fastgpt.io/deploy/docker/main/global/docker-compose.pg.yml -o docker-compose.source.yml

2. Download install.sh to the server:

curl -fsSL https://doc.fastgpt.io/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 credentials and writes the S3 address when needed. After generation, log in with the root login details 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 service tokens, database passwords, and S3 addresses (v4.17.3+ initializes with 123456 and requires changing the password in the first-login activation modal; v4.17.2 and earlier use DEFAULT_ROOT_PSW).

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, also replace the sandbox-related images in the Compose file and update AGENT_SANDBOX_SEALOS_IMAGE or AGENT_SANDBOX_OPENSANDBOX_IMAGE so the sandbox provider can pull the matching images. See OpenSandbox Configuration for details.

2. Modify Environment Variables

You must set FE_DOMAIN in fastgpt-app to the complete external URL accessible to client browsers, such as https://fastgpt.example.com. It includes a scheme, host, and optional port.

When Agent/Skill Sandbox is enabled, also configure:

• AGENT_SANDBOX_PROXY_URL: the browser-accessible Sandbox Proxy WebSocket URL using ws:// or wss://, such as wss://sandbox-proxy.example.com, which must be forwarded to the Sandbox Proxy host port (default 3006).
• Version 4.16 and later additionally require AGENT_SANDBOX_PREVIEW_PROXY_URL: the browser-accessible HTTP(S) URL for sandbox file previews, such as https://sandbox-proxy.example.com, forwarded to the same host port.

The interactive install script prompts for these addresses before the final confirmation.

For Zilliz version, you also need credentials — see Obtain Zilliz Cloud Credentials. Other versions can skip to the next step.

3. Open External Ports / Configure Domain

The following services must be reachable. For direct access, open the host ports printed by the script; with a reverse proxy, the proxy owns the public ports:

1. Port 3000 by default (FastGPT main service; change the host port with FASTGPT_PORT)
2. Port 9000 (S3 object storage service; in default short-proxy mode FastGPT proxies private files, while short-redirect mode or direct browser access to public bucket assets such as plugin logos requires configuring STORAGE_EXTERNAL_ENDPOINT in Compose and opening port 9000)
3. Port 3006 by default (FastGPT Agent Sandbox Proxy service; change the host port with FASTGPT_SANDBOX_PROXY_PORT)

4. Start Containers

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

# Pre-pull all service and sandbox runtime images
docker compose --profile prepull pull

# Start containers
docker compose up -d

5. Access FastGPT

Access FastGPT via the port/domain opened in step 3. The login username is root:

• Version v4.17.3 and later: The initial password is fixed at 123456. An activation modal requires setting a new password upon first login (any residual DEFAULT_ROOT_PSW variable in v4.17.3+ Compose templates is ignored). If forgotten, reset the password using the built-in CLI script. See Modify and Reset Root Password.
• Legacy versions (v4.17.2 and earlier): The password is set via DEFAULT_ROOT_PSW in docker-compose.yml. When deploying with the interactive script, a random password is generated and displayed upon completion. Each container restart updates the password to this value.

6. Configure Models

• After first login, if models are not yet configured, the system prompts that related models or embedding models are not configured and guides you to the model configuration page. At least a language model and an embedding model are required.
• If the redirect doesn't happen, go to Admin → System Resources → System Models 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 provides the runtime environment, and administrators can install system plugins on demand under Admin → (Commercial Edition: System Resources →) System Tools:

• 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.

8. Obtain Zilliz Cloud Credentials (For Zilliz Compose Templates)

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

Post-Deployment Operations and Troubleshooting

• Routine Operations: See Environment Variables to customize container variables, Modify and Reset Root Password to update administrator credentials, Upgrade Instructions before upgrading across releases, and Migrate MongoDB 5.x to 8.x (Dump/Restore) when migrating the bundled MongoDB 5.x container.
• Troubleshooting: For component version compatibility, S3 connection errors, MongoDB replica set initialization, relation "modeldata" does not exist, Illegal instruction, or port conflicts, see General Troubleshooting.