Run Percona ClusterSync for MongoDB in Docker¶

You can run Percona ClusterSync for MongoDB as a Docker container. This is useful for such use cases:

you want to try out Percona ClusterSync for MongoDB quickly without complex setup
your MongoDB clusters also run in Docker
you want to isolate Percona ClusterSync for MongoDB in a containerized environment.

Docker images of Percona ClusterSync for MongoDB are hosted publicly on Docker Hub .

For more information about using Docker, see the Docker Docs .

Make sure that you are using the latest version of Docker. The ones provided via apt and yum may be outdated and cause errors.

By default, Docker will pull the image from Docker Hub if it is not available locally.

Prerequisites¶

You need to either deploy MongoDB or Percona Server for MongoDB as your source and target clusters or use existing deployments. Both clusters can run in Docker containers, on virtual machines, or in cloud environments.
The PCSM container must be able to reach all nodes in both source and target MongoDB clusters over the network. This includes:
- All replica set members that can become primary
- The mongos nodes in source and target clusters
Create users in both source and target clusters with appropriate permissions for authentication.

For example, to create a user for PCSM in Percona Server for MongoDB running in Docker, use the following command, replacing psmdb with your container name, source with the username and mys3cretpAss with the password:
```
docker exec -it psmdb mongosh --eval '
db.getSiblingDB("admin").createUser({
  user: "source",
  pwd: "mys3cretpAss",
  roles: ["backup", "clusterMonitor", "readAnyDatabase"]
});'
```
See Configure authentication for details.
Your source cluster has some data to verify the replication.

Deploy source and target clusters¶

In this example configuration we spin up single-node replica sets in Docker containers named psmdb-source and psmdb-target, respectively.

In production, use the minimum recommended three member replica sets.

If you already have source and target clusters deployed, skip this step.

Create a Docker network:
```
$ docker network create mymongo
```

Start Percona Server for MongoDB containers

Start the container for the source replica set:

docker run -d \
  --name psmdb-source \
  --net mymongo \
  -p 27017:27017 \
  percona/percona-server-mongodb:8.0 \
  mongod --replSet rs1 --bind_ip_all

Start the container for the target replica set and map a different port:

docker run -d \
  --name psmdb-target \
  --net mymongo \
  -p 27018:27017 \
  percona/percona-server-mongodb:8.0 \
  mongod --replSet rs2 --bind_ip_all

Initialize replica sets:

For the source:

docker exec -it psmdb-source mongosh --eval 'rs.initiate({
  _id: "rs1",
  members: [{ _id: 0, host: "psmdb-source:27017" }]
})'

For the target:

docker exec -it psmdb-target mongosh --eval 'rs.initiate({
  _id: "rs2",
  members: [{ _id: 0, host: "psmdb-target:27017" }]
})'

Verify that your replica sets are initialized and running:

docker exec -it psmdb-source mongosh --eval 'rs.status()'
docker exec -it psmdb-target mongosh --eval 'rs.status()'

Create a user for Percona ClusterSync for MongoDB on the source:

docker exec -it psmdb-source mongosh --eval '
db.getSiblingDB("admin").createUser({
  user: "source",
  pwd: "mys3cretpAss",
  roles: ["backup", "clusterMonitor", "readAnyDatabase"]
});'

Create a user for Percona ClusterSync for MongoDB on the target:

docker exec -it psmdb-target mongosh --eval '
db.getSiblingDB("admin").createUser({
  user: "target",
  pwd: "t0ps3cret",
  roles: ["backup", "clusterMonitor", "readAnyDatabase"]
});'

Start Percona ClusterSync for MongoDB¶

Start the PCSM container. You can specify connection strings using environment variables or command-line flags:

Environment variablesCommand-line flags

Use the PCSM_SOURCE_URI and PCSM_TARGET_URI environment variables:

$ docker run --name pcsm1 --network mymongo -d \
    -e PCSM_SOURCE_URI="mongodb://<source-user>:<source-password>@psmdb-source:27017" \
    -e PCSM_TARGET_URI="mongodb://<target-user>:<target-password>@psmdb-target:27017" \
    percona/percona-clustersync-mongodb:latest

Replace <source-user>:<source-password> and <target-user>:<target-password> with the credentials of the users you created for pcsm process in the source and target clusters.

Pass the --source and --target flags directly:

$ docker run --name pcsm1 --network mymongo -d \
    percona/percona-clustersync-mongodb:latest \
    --source "mongodb://<source-user>:<source-password>@psmdb-source:27017" \
    --target "mongodb://<target-user>:<target-password>@psmdb-target:27017"

Replace <source-user>:<source-password> and <target-user>:<target-password> with the credentials of the users you created for pcsm process in the source and target clusters.

Additional options

You can combine environment variables with command-line flags or add other options:

$ docker run --name pcsm1 --network mymongo -d \
    -e PCSM_SOURCE_URI="mongodb://source:password@psmdb-source:27017" \
    -e PCSM_TARGET_URI="mongodb://target:password@psmdb-target:27017" \
    -p 2242:2242 \
    percona/percona-clustersync-mongodb:latest \
    --port 2242 \
    --log-level debug

See startup configuration for all available options.

Check the initial status of PCSM:
```
$ docker exec -it pcsm1 pcsm status
```
The status should be idle, indicating PCSM is ready to accept requests.

Run PCSM¶

Start the replication process:
```
docker exec -it pcsm1 pcsm start
```
Monitor replication by checking the status:
```
docker exec -it pcsm1 pcsm status
```
View logs to monitor activity:
```
$ docker logs -f pcsm1
```
Finalize the replication when you no longer need it:
```
docker exec -it pcsm1 pcsm finalize
```
Note that this is one-time operation. You cannot restart the replication after you finalized it. If you run the start command, PCSM will start the replication anew, with the initial sync.

Next steps¶

Use Percona ClusterSync for MongoDB

Last update: January 14, 2026
Created: January 14, 2026