percona/percona-server-mongodb

!logo

What is Percona Server for MongoDB?

"Percona Server for MongoDB is a a source-available, fully compatible drop-in replacement for MongoDB Community Edition. It includes enterprise security, backup and developer-friendly features otherwise available only in the MongoDB EE.

Key features include:

• Encrypted WiredTiger Storage Engine.
• External Authentication and Authorization - enables authentication through OpenLDAP/AD or Kerberos.
• Audit logging, log redaction and query database interactions of users or applications.
• Integration with Percona ToolKit and Percona Monitoring and Management - provides query performance analytics and troubleshooting tools.
• Compatible with Percona Operator for MongoDB - easily deploy and manage complex MongoDB topologies on Kubernetes."

For more information and related downloads for Percona Server and other Percona products, please visit [***]

Product Documentation

• Version 4.0
• Version 4.2
• Version 4.4
• Version 5.0
• Version 6.0

Percona Server for MongoDB Docker Images

Percona Server for MongoDB Docker images, created and maintained by the Percona team.

Images are updated when new releases are published.

How to Use the Images

Start a Percona Server for MongoDB Instance

Start a Percona Server for MongoDB container as follows:

docker run --name container-name  -d percona/percona-server-mongodb:tag

Where container-name is the name you want to assign to your container and tag is the tag specifying the version you want. See the list above for relevant tags, or look at the https://hub.docker.com/r/percona/percona-server-mongodb/tags/.

Accessing Container Shell

Use the following command to get the access to the bash shell and run commands inside the Docker container:

docker exec -it container-name bash

where container-name is the name of your database container.

Connect to Percona Server for MongoDB from an Application running locally

To access Percona Server for MongoDB from an application that is running locally, you need to expose the port using the -p option. The following example shows exposing the standard MongoDB port (27017)

docker run --name container-name  -p 27017:27017 -d percona/percona-server-mongodb:tag 

where container-name is the name of your database container.

Using this method, you will be able to connect to your MongoDB instance on mongodb://localhost:27017.

Connect to Percona Server from an Application in Another Docker Container

This image exposes the standard MongoDB port (27017), so container linking makes the instance available to other containers. Start other containers like this in order to link it to the Percona Server for MongoDB container:

docker run --name app-container-name --link container-name -d app-that-uses-mongodb

Connect to Percona Server for MongoDB from the MongoDB Command Line Client

The following command starts another container instance and runs the mongo/ mongosh command line client against your original container, allowing you to execute commands against your database:

docker run -it --link psmdb --rm percona/percona-server-mongodb:tag mongo mongodb://MONGODB_SERVER:PORT/DB_NAME

For Percona Server for MongoDB 6.0+ and onwards, the mongosh command line client is used. To connect to it, run the command as follows

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

Set MONGODB_SERVER with the IP address of the psmdb container, PORT - with the port of your MongoDB Server (default value is 27017), and DB_NAME with 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

Environment Variables

When you start the percona/percona-server-mongodb image, you can adjust the initialization of the MongoDB instance by passing one or more environment variables on the docker run command line. Note that none of the variables below will have any effect if you start the container with a data directory that already contains a database: any pre-existing database will always be left untouched on container startup.

MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD

Using these variables in conjunction allows you to create a new user and set that user's password. This user is created in the admin authentication database and given the role of root.

The following is an example of using these two variables to create a MongoDB instance and then using the mongo CLI to connect against the admin authentication database.

$ docker run -d --name container-name \
       -e MONGO_INITDB_ROOT_USERNAME=mongoadmin \
       -e MONGO_INITDB_ROOT_PASSWORD=secret \
       percona/percona-server-mongodb:tag

$ docker exec -it container-name \
       mongo -u mongoadmin \
                    -p secret \
                    --authenticationDatabase admin \
                    some-db
> db.getName();
   some-db

Both variables are required for a user to be created. If both are present, then MongoDB will start with authentication enabled (mongod --auth). To read more about authentication in MongoDB, refer to this upstream documentation:

• mongod --auth
• Security > Authentication
• Security > Role-Based Access Control
• Security > Role-Based Access Control > Built-In Roles
• Security > Enable Auth (tutorial)

Docker Secrets

As an alternative to passing sensitive information via environment variables, _you can specify the variables and their values in an environment file and pass this file during the container start. For example:

 docker run --name container-name --env-file path/to/mongo-env -d percona/percona-server-mongodb:tag

where container-name is the name of your database container and path/to/mongo-env is the path to the environment file on your local filesystem.

Notes, Tips, Gotchas

Where to Store Data

There are many two ways to store data used by applications that run in Docker containers. We maintain our usual stance and encourage users to investigate the options and use the method that best suits their use case. Here are some of the options available:

• Let Docker manage the storage of your database data by writing the database files to disk on the host system using its own internal volume management. The current solutions, devicemapper, aufs and overlayfs have negative performance records.
• Create a data directory on the host system (outside the container on high performance storage) and mount this to a directory visible from inside the container. This places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The user needs to make sure that the directory exists, and that permissions and other security mechanisms on the host system are set up correctly.

The Docker documentation is a good starting point for understanding the different storage options and variations, and there are multiple blog and forum postings that discuss and give advice in this area. We will simply show the basic procedure here for the latter option above:

1. Create a data directory on a suitable volume on your host system, e.g. /local/datadir.
2. Start your container like this:

    docker run --name container-name -v /local/datadir:/data/db -d percona/percona-server-mongodb:tag

The -v /local/datadir:/data/db part of the command mounts the /local/datadir directory from the underlying host system as /data/db inside the container, where MongoDB by default will write its data files.

Viewing Percona Server for MongoDB logs

The Percona Server for MongoDB Server log is available through Docker's container log:

$ docker logs container-name

where container-name is the name of your database container.

Passing options to the server

You can pass arbitrary command line options to the server by appending them to the run command:

docker run --name my-container-name -d percona/percona-server-mongodb --option1=value --option2=value

User Feedback

We welcome your feedback!