Run Milvus with Docker Compose (Linux)

This page illustrates how to launch a Milvus instance in Docker using Docker Compose.

Prerequisites

• Install Docker.
• Install the Docker Compose plugin (V2 or later) and verify it with docker compose version. These instructions use docker compose, not the legacy docker-compose V1 command.
• Check the requirements for hardware and software prior to your installation.

Install Milvus

Milvus provides a Docker Compose configuration file in the Milvus repository. Download the configuration for v3.0.5 and start a new deployment:

# Download the configuration file
$ wget https://github.com/milvus-io/milvus/releases/download/v3.0.5/milvus-standalone-docker-compose.yaml -O docker-compose.yaml

# Start Milvus
$ sudo docker compose up -d

Creating milvus-etcd  ... done
Creating milvus-minio ... done
Creating milvus-standalone ... done

After starting up Milvus,

• Containers named milvus-standalone, milvus-minio, and milvus-etcd are up.
  • The milvus-etcd container does not expose any ports to the host and maps its data to volumes/etcd in the current folder.
  • The milvus-minio container serves ports 9000 and 9001 locally with the default authentication credentials and maps its data to volumes/minio in the current folder.
  • The milvus-standalone container serves ports 19530 locally with the default settings and maps its data to volumes/milvus in the current folder.

You can check if the containers are up and running using the following command:

$ docker compose ps

NAME                IMAGE   COMMAND                  SERVICE      CREATED         STATUS                   PORTS
milvus-etcd         …       "etcd -advertise-cli…"   etcd         2 minutes ago   Up 2 minutes (healthy)   2379-2380/tcp
milvus-minio        …       "/usr/bin/docker-ent…"   minio        2 minutes ago   Up 2 minutes (healthy)   9000-9001/tcp
milvus-standalone   …       "/tini -- milvus run…"   standalone   2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:9091->9091/tcp, 0.0.0.0:19530->19530/tcp

You can also access Milvus WebUI at http://127.0.0.1:9091/webui/ to learn more about the your Milvus instance. For details, refer to Milvus WebUI.

To try the running server, follow the Use an existing Milvus server path in Quickstart and connect to http://localhost:19530. Do not use the local .db connection block, which starts a separate Milvus Lite database.

(Optional) Update Milvus configurations

To update Milvus configuration to suit your needs, you need to modify the /milvus/configs/user.yaml file within the milvus-standalone container.

1. Access the milvus-standalone container.

   docker exec -it milvus-standalone bash
   

2. Add extra configurations to override the default ones. The following assumes that you need to override the default proxy.healthCheckTimeout. For applicable configuration items, refer to System Configuration.

   cat << EOF > /milvus/configs/user.yaml
   # Extra config to override default milvus.yaml
   proxy:
     healthCheckTimeout: 1000 # ms, the interval that to do component healthy check
   EOF
   

3. Restart the milvus-standalone container to apply the changes.

   docker restart milvus-standalone
   

Stop and delete Milvus

You can stop and delete this container as follows

# Stop Milvus
$ sudo docker compose down

# Delete service data
$ sudo rm -rf volumes

Upgrade an existing deployment

For a Milvus 2.6.x standalone deployment, follow Upgrade Milvus Standalone with Docker Compose. Back up metadata and persistent data, preserve the existing dependencies and configuration, and validate the documented source-to-target upgrade path before changing the Milvus image. Do not replace an older deployment’s Compose file with the new-installation configuration above.

Message Queue limitations: When upgrading to Milvus v3.0.5, you must maintain your current message queue choice. Switching between different message queue systems during the upgrade is not supported. Support for changing message queue systems will be available in future versions.

Milvus 2.6.x and later default to Woodpecker, while 2.5.x deployments default to RocksMQ. If the deployment you are upgrading still runs RocksMQ, pin it in user.yaml before changing the Milvus image, so the upgraded instance keeps its existing message queue instead of starting with the new default:

# user.yaml — keep RocksMQ across the upgrade
mq:
  type: rocksmq

After the upgraded instance is running on v3.0.5, you can move from RocksMQ to Woodpecker with Switch Message Queue, which is available in Milvus 3.0 and later.

Optional dependencies

This deployment runs Woodpecker (embedded, MinIO WAL backend) for messaging, etcd for metadata, and MinIO for object storage. To use a different message queue or connect external object storage / metadata, see:

• Message queue: Woodpecker (default) · Pulsar · Kafka · RocksMQ
• Object storage: MinIO (default) · AWS S3 · Azure Blob · GCP Cloud Storage · Aliyun OSS · Tencent COS · Huawei OBS · S3-compatible
• Metadata: etcd

What’s next

Having installed Milvus in Docker, you can:

• Check Quickstart to see what Milvus can do.

• Learn the basic operations of Milvus:

  • Manage Databases
  • Manage Collections
  • Manage Partitions
  • Insert, Upsert & Delete
  • Single-Vector Search
  • Hybrid Search

• Upgrade Milvus Standalone with Docker Compose.

• Scale your Milvus cluster.

• Deploy your Milvus cluster on clouds:

  • Amazon EKS
  • Google Cloud
  • Microsoft Azure

• Explore Milvus WebUI, an intuitive web interface for Milvus observability and management.

• Explore Milvus Backup, an open-source tool for Milvus data backups.

• Explore Birdwatcher, an open-source tool for debugging Milvus and dynamic configuration updates.

• Explore Attu, an open-source GUI tool for intuitive Milvus management.

• Monitor Milvus with Prometheus.