Run Percona Server for MongoDB in a Docker container¶

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

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

Note

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.

We gather Telemetry data to understand the use of the software and improve our products.

To run the latest Percona Server for MongoDB 8.0 in a Docker container, run the following command as the root user or via sudo:

$ docker run -d --name psmdb -p 27017:27017 --restart always percona/percona-server-mongodb:<TAG>-multi

The command does the following:

The docker run command instructs the docker daemon to run a container from an image.
The -d option starts the container in detached mode (that is, in the background).
The --name option assigns a custom name for the container that you can use to reference the container within a Docker network. In this case: psmdb.
The -p option binds the container’s port 27017 to TCP port 27017 on all host network interfaces. This makes the container accessible externally.
The --restart option defines the container’s restart policy. Setting it to always ensures that the Docker daemon will start the container on startup and restart it if the container exits.
percona/percona-server-mongodb is the name of the image to derive the container from.
<TAG>-multi is the tag specifying the version you need. For example, 8.0.4-1-multi. The multi part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image. See the full list of tags.

Connecting from another Docker container¶

The Percona Server for MongoDB container exposes standard MongoDB port (27017), which can be used for connection from an application running in another container.

For example, to set up a replica set for testing purposes, you have the following options:

Interconnect the mongod nodes in containers on a default bridge network. In this scenario, containers communicate with each other by their IP address.
Create a user-defined network and interconnect the mongod nodes on it. In this scenario, containers communicate with each other by name.
Automate the container provisioning and the replica set setup via the Docker Compose tool.

The following example demonstrates the setup on x86_64 platforms. The rs101, rs102, rs103 are the container names for Percona Server for MongoDB and rs is the replica set name.

For ARM64 architectures, change the image to percona/percona-server-mongodb:<TAG>-arm64.

Bridge networkUser-defined networkDocker Compose

When you start Docker, a default bridge network is created and all containers are automatically attached to it unless otherwise specified.

Start the containers and expose different ports

$ docker run --rm -d --name rs101 -p 27017:27017  percona/percona-server-mongodb:8.0 --port=27017 --replSet rs
$ docker run --rm -d --name rs102 -p 28017:28017  percona/percona-server-mongodb:8.0 --port=28017 --replSet rs
$ docker run --rm -d --name rs103 -p 29017:29017  percona/percona-server-mongodb:8.0 --port=29017 --replSet rs

Check that the containers are started

$ docker container ls

Output:

CONTAINER ID  IMAGE                                         COMMAND               CREATED         STATUS             PORTS                     NAMES
3a4b70cd386b  percona/percona-server-mongodb:8.0  --port=27017 --re...  3 minutes ago   Up 3 minutes ago   0.0.0.0:27017->27017/tcp  rs101
c9b40a00e32b  percona/percona-server-mongodb:8.0  --port=28017 --re...  11 seconds ago  Up 11 seconds ago  0.0.0.0:28017->28017/tcp  rs102
b8aebc00309e  percona/percona-server-mongodb:8.0  --port=29017 --re...  3 seconds ago   Up 3 seconds ago   0.0.0.0:29017->29017/tcp  rs103

Get the IP addresses of each container

$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' rs101
$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' rs102
$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' rs103

Interconnect the containers and initiate the replica set. Replace rs101SERVER, rs102SERVER and rs103SERVER with the IP address of each respective container.

$ docker exec -ti rs101 mongosh --eval 'config={"_id":"rs","members":[{"_id":0,"host":"rs101SERVER:27017"},{"_id":1,"host":"rs102SERVER:28017"},{"_id":2,"host":"rs103SERVER:29017"}]};rs.initiate(config);'

Check your setup

$ docker exec -ti rs101 mongosh --eval 'rs.status()'

You can isolate desired containers in a user-defined network and provide DNS resolution across them so that they communicate with each other by hostname.

Create the network:
```
$ docker network create my-network
```

Start the containers and connect them to your network, exposing different ports

$ docker run --rm -d --name rs101 --net my-network -p 27017:27017  percona/percona-server-mongodb:8.0 --port=27017 --replSet rs
$ docker run --rm -d --name rs102 --net my-network -p 28017:28017  percona/percona-server-mongodb:8.0 --port=28017 --replSet rs
$ docker run --rm -d --name rs103 --net my-network -p 29017:29017  percona/percona-server-mongodb:8.0 --port=29017 --replSet rs

Alternatively, you can connect the already running containers to your network:

$ docker network connect my-network rs101 rs102 rs103

Interconnect the containers and initiate the replica set.

$ docker exec -ti rs101 mongosh --eval 'config={"_id":"rs","members":[{"_id":0,"host":"rs101:27017"},{"_id":1,"host":"rs102:28017"},{"_id":2,"host":"rs103:29017"}]};rs.initiate(config);'

Check your setup

$ docker exec -ti rs101 mongosh --eval 'rs.status()'

As the precondition, you need to have Docker Engine and Docker Compose on your machine. Refer to Docker documentation for how to get Docker Compose.

Create a compose file and define the services in it.

docker-compose.yaml

version: "3"
services:
  rs101:
    image: percona/percona-server-mongodb:8.0
    container_name: rs101
    hostname: rs101
    ports:
      - "27017:27017"
    networks:
      - my-network
    command: "--port=27017 --replSet rs"

  rs102:
    image: percona/percona-server-mongodb:8.0
    container_name: rs102
    hostname: rs102
    ports:
      - "28017:28017"    
    networks:
      - my-network
    command: "--port=28017 --replSet rs"

  rs103:
    image: percona/percona-server-mongodb:8.0
    container_name: rs103
    hostname: rs103
    ports:
      - "29017:29017"    
    networks:
      - my-network
    command: "--port=29017 --replSet rs"

  rs-init:
    image: percona/percona-server-mongodb:8.0
    container_name: rs-init
    restart: "no"
    networks:
      - my-network
    depends_on:
      - rs101
      - rs102
      - rs103
    command: >
      mongosh --host rs101:27017 --eval 
      '
      config = {
      "_id" : "rs",
      "members" : [
        {
          "_id" : 0,
          "host" : "rs101:27017"
        },
        {
          "_id" : 1,
          "host" : "rs102:28017"
        },
        {
          "_id" : 2,
          "host" : "rs103:29017"
        }
      ]
      };
      rs.initiate(config);
      ' 
networks:
  my-network:
    driver: bridge

Build and run the replica set with Compose
```
$ docker compose up -d
```

Check your setup

$ docker exec -ti rs101 mongosh --eval 'rs.status()'

Connecting with the `mongosh` shell¶

To start another container with the mongosh shell that connects to your Percona Server for MongoDB container, run the following command:

$ docker run -it --link psmdb --rm percona/percona-server-mongodb:8.0 mongosh mongodb://MONGODB_SERVER:PORT/DB_NAME

Set MONGODB_SERVER, PORT, and DB_NAME with the IP address of the psmdb container, the port of your MongoDB Server (default value is 27017), and the name of the database you want to connect to.

You can get the IP address by running this command:

$ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' psmdb

Get expert help¶

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert Join Percona Squad

Run Percona Server for MongoDB in a Docker container¶

Connecting from another Docker container¶

Connecting with the mongosh shell¶

Get expert help¶

Connecting with the `mongosh` shell¶