A MongoDB server for one application
A server that runs MongoDB from MongoDB's own package repository, with
access control on, an administrator, and one user for an application named
shop.
Set the server's address in inventories/example.yml, which also holds the
MongoDB series that the server runs. Choose two passwords and give them to
MMX in environment variables of the controller machine, the machine where
you run mmx:
export MONGODB_ADMIN_PASSWORD='choose-a-long-password'
export SHOP_MONGODB_PASSWORD='choose-another-long-password'
mmx dryrun configure
mmx run configure
mmx run configure
On the node, in order:
- MMX adds MongoDB's package repository,
repo.mongodb.org, with the key that signs its packages. - MMX installs the packages
mongodb-org-server, the server, andmongodb-mongosh, MongoDB's shell. - MMX writes the server's settings to
/etc/mongod.conffromtemplates/mongod.conf, with access control on, starts the server, and keeps it starting at boot. - MMX waits until the server's port 27017 answers.
- MMX creates the administrator: the user
adminin the databaseadmin, with the roleroot. - MMX creates the application's user: the user
shopin the databaseshop, with the rolereadWriteon that database and no other.
The second run changes nothing. The first dryrun, before MongoDB is
installed, reports the two user tasks not_checked: MMX cannot look into a
server that is not installed yet. A run after you changed
SHOP_MONGODB_PASSWORD changes only the password of the database user
shop.
The application then connects with
mongodb://shop:<password>@127.0.0.1:27017/shop. Write the application's
configuration file with a file task that reads the same secret,
{{ .secrets.shop_mongodb_password }}.
Distributions
The example works on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10. MongoDB serves packages for each of them.
What the playbook does differently on each:
| Distribution | Repository | The server's data |
|---|---|---|
| Debian | repo.mongodb.org/apt/debian, component main |
/var/lib/mongodb |
| Ubuntu | repo.mongodb.org/apt/ubuntu, component multiverse |
/var/lib/mongodb |
| Red Hat family | repo.mongodb.org/yum/redhat/<major version> |
/var/lib/mongo |
The MongoDB series
MongoDB publishes each series, such as 8.0 or 9.0, in a repository of its
own, so a server stays in its series until you change it. The series belongs
to the server, so the inventory holds it: three variables of the group
mongodb_servers in inventories/example.yml. The three MongoDB variables
belong together, because each series has its own signing key:
mongodb_series |
mongodb_signing_key_url |
mongodb_signing_key_sha256 |
|---|---|---|
9.0 |
https://pgp.mongodb.com/server-9.asc |
a8ec953b159e65ee2e327dde5506008d7693c3c6c3841beed421ec429bd10162 |
8.0 |
https://pgp.mongodb.com/server-8.0.asc |
8c467ea138207ee8d0cbbce3e005c82c73c81b3263e7909bdc36b9a1feff14f6 |
7.0 |
https://pgp.mongodb.com/server-7.0.asc |
b254e7858367d4c1762f931762c4db3ad7a6a0af11f3a965b709e9933c52852b |
# inventories/example.yml
groups:
mongodb_servers:
nodes: [database01]
vars:
mongodb_series: "8.0"
mongodb_signing_key_url: https://pgp.mongodb.com/server-8.0.asc
mongodb_signing_key_sha256: 8c467ea138207ee8d0cbbce3e005c82c73c81b3263e7909bdc36b9a1feff14f6
A server of the group that runs another series than the others gets the
three values in its own vars in the inventory, which replace the group's.
Not every distribution has every series: Debian 13 has only 9.0, and Ubuntu 24.04 and 26.04 have none before 8.0.
Why it is written this way
MongoDB's own repository. No distribution packages MongoDB. MMX fetches the signing key on the controller machine and checks it against the SHA-256 in the playbook, so a node never trusts a key that the project did not name.
MMX starts the server, not the package. The packages start nothing. The
systemd_service task starts the server after /etc/mongod.conf is in
place, so the server never runs without access control, and restarts it
when the file changes.
The administrator names itself as its login. While a server with access
control has no user, MongoDB lets a connection from the server itself create
the first user without a login. So the first run of the administrator's task
needs no login, and every later run logs in as admin with the same secret.
To change the administrator's password, give the new password as password
and keep the old password as login_password for one run. Make the password
change a run of its own, with only the administrator's node task.
Afterwards, use the new password for password and login_password.
See the administrator
password-change
instructions.
The passwords come from secrets. mmx_project_settings.yml binds the
secrets mongodb_admin_password and shop_mongodb_password to the two
environment variables. To keep mongodb_admin_password and
shop_mongodb_password in the project's encrypted vault instead, remove
secrets_from_env from mmx_project_settings.yml. Write the secrets with
mmx secrets edit. The passwords reach MongoDB's shell
through its standard input, and are in no command line and in none of MMX's
records.
An application on another machine. The server listens only on
127.0.0.1. Add the server's address in the private network to bindIp in
templates/mongod.conf; the next run restarts the server.
For every input of mongodb_user, its errors, a replica set, and a server
before MongoDB 8.2, see
the module's page.
This page is examples/mongodb-server-for-one-application/README.md in the MMX repository.