Initialization of a user defined database, username, and password using environment variables

[johnwyles]

This issue (I would call it a bug but perhaps it is a feature request) is that users would like to a la docker-compose.yml and/or environment variables be able to set a database with a username and password they specify upon launch of the image.

Background:

This issue was filed #174 and closed because the behavior of a PR #145 was mentioned as the solution. What #145 actually does and what users expect are entirely different. What PR #145 does is set a user with elevated permissions (i.e. "root" user) that has superuser access to the entire MongoDB instance (as mentioned in #174 (comment). However what most users expect from these environment variables is that a database they specify is initialized with the username and password they have set. It is confusing that these environment variables (MONGO_INITDB_DATABASE, MONGO_INITDB_ROOT_PASSWORD and MONGO_INITDB_ROOT_USERNAME) pertain to only setting a user with the role root on the database admin and initializing an user specified database for .js and .sh scripts in /docker-entrypoint-initdb.d/ to be run against.

Proposal:

We should make the environment variables very explicitly named in what they do in addition to adding others for the behavior I think most users come to expect when reading the variable names. Since it is the case most users would like their instance initialized with a database of their specification we should add this feature to meet that expectation.

• We keep MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD
• We remove MONGO_INITDB_DATABASE as it is misleading
• We add MONGO_INITDB_ROOT_DATABASE and allow it to override the hardcoded admin database
• We add MONGO_USERDB_ADMIN_USERNAME, MONGO_USERDB_ADMIN_PASSWORD, and MONGO_USERDB_ADMIN_DATABASE
• We update the documentation to state:
  • MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD, and MONGO_INITDB_ROOT_DATABASE will be used for the root role to Mongo
• MONGO_USERDB_ADMIN_USERNAME, MONGO_USERDB_ADMIN_PASSWORD, and MONGO_USERDB_ADMIN_DATABASE will be used to initialize a user specified database
• That all of the .js and .sh scripts a user supplies in /docker-entrypoint-initdb.d/ will be executed against MONGO_USERDB_ADMIN_DATABASE

Reasons for change:

• The variables MONGO_INITDB_ROOT_PASSWORD and MONGO_INITDB_ROOT_USERNAME are only used for the admin database
• Currently all MONGO_INITDB_DATABASE does is have operations used against it whenever a user has dropped in .js or .sh scripts into /docker-entrypoint-initdb.d/. This unclear unless you look at docker-entrypoint.sh in this repository and no where clearly stated in the documentation as such
• The documentation is unclear and the only way to hack in a user initialized database with a username and password on image launch is to also create a script in /docker-entrypoint-initdb.d/ which then places burden on the user to maintain the root role credentials in environment variables which live separately from a custom .js or .sh script which they have to volume into the image

References:

• Issue: Initialize admin username/password and DB doesn't seems to be working ... #174
• PR: Add "docker-entrypoint-initdb.d" behavior which mimics PostgreSQL, including (optional) automated "root" user creation #145

Involved Persons:

@mmi-rperez
@tianon
@vutran1710
@yosifkit
@lonix1
@johnwyles

[lonix1]

Agreed! There should be an easy way to spin up a container, with a new database, username and password - all specified in docker-compose / environment variables.

[yosifkit]

I understand your confusion. We only create a user with the root role (ie superuser as is done in the Postgres image) and users expect that the user is created in the database that they specified by MONGO_INITDB_DATABASE. This is not possible for the root role. The root role only exists in the admin database (probably for security reasons). Any other role not created in the admin database would not have full access to control MongoDB.

See also,

• Security > Security Reference > Built-In Roles > Superuser Roles
• Security > Role-Based Access Control > Built-In Roles

As for the database not existing, that is just how MongoDB works as I have explained before. If nothing is inserted the database does not exist (or conversely every database exists, you just have to use it).

I'm mostly against adding more environment variables for creating a non-admin user, especially if it breaks backwards compatibility. We try to keep the images as close to upstream releases as possible with minimal maintenance and the entrypoint script is already very complex.

---

A simple Dockerfile:

FROM mongo:4.0
COPY custom-user.sh /docker-entrypoint-initdb.d/

and a short custom-user.sh file:

#!/bin/bash
set -e;

# a default non-root role
MONGO_NON_ROOT_ROLE="${MONGO_NON_ROOT_ROLE:-readWrite}"

if [ -n "${MONGO_NON_ROOT_USERNAME:-}" ] && [ -n "${MONGO_NON_ROOT_PASSWORD:-}" ]; then
	"${mongo[@]}" "$MONGO_INITDB_DATABASE" <<-EOJS
		db.createUser({
			user: $(_js_escape "$MONGO_NON_ROOT_USERNAME"),
			pwd: $(_js_escape "$MONGO_NON_ROOT_PASSWORD"),
			roles: [ { role: $(_js_escape "$MONGO_NON_ROOT_ROLE"), db: $(_js_escape "$MONGO_INITDB_DATABASE") } ]
			})
	EOJS
else
	# print warning or kill temporary mongo and exit non-zero
fi

Combine that with automated builds (https://docs.docker.com/docker-hub/builds/) and repository links (https://docs.docker.com/docker-hub/builds/#repository-links) and it's reasonably easy to have an up-to-date image built FROM mongo with the custom non-root user creation modifications.

$ docker run -d -e MONGO_INITDB_ROOT_USERNAME=root -e MONGO_INITDB_ROOT_PASSWORD=supersecret -e MONGO_INITDB_DATABASE=notadmin -e MONGO_NON_ROOT_USERNAME=normal -e MONGO_NON_ROOT_PASSWORD=secret --name some-mongo custom-mongo

$ docker run -it --rm --link some-mongo mongo:4.0 mongo -u normal -p secret some-mongo/notadmin
MongoDB shell version v4.0.6
connecting to: mongodb://some-mongo:27017/notadmin?gssapiServiceName=mongodb
Implicit session: session { "id" : UUID("0941eaa4-9180-4012-a24c-60fe8369b06a") }
MongoDB server version: 4.0.6
Welcome to the MongoDB shell.
For interactive help, type "help".
For more comprehensive documentation, see
	http://docs.mongodb.org/
Questions? Try the support group
	http://groups.google.com/group/mongodb-user
> use admin;
switched to db admin
> db.users.findOne();
2019-02-05T23:57:10.838+0000 E QUERY    [js] Error: error: {
	"ok" : 0,
	"errmsg" : "not authorized on admin to execute command { find: \"users\", filter: {}, limit: 1.0, singleBatch: true, lsid: { id: UUID(\"c86d23b2-9ed4-4799-9d3e-74f327366550\") }, $db: \"admin\" }",
	"code" : 13,
	"codeName" : "Unauthorized"
} :
_getErrorWithCode@src/mongo/shell/utils.js:25:13
DBCommandCursor@src/mongo/shell/query.js:708:1
DBQuery.prototype._exec@src/mongo/shell/query.js:113:28
DBQuery.prototype.hasNext@src/mongo/shell/query.js:288:5
DBCollection.prototype.findOne@src/mongo/shell/collection.js:260:10
@(shell):1:1
> use notadmin;
switched to db notadmin
> db.users.findOne();
null

---

This unclear unless you look at docker-entrypoint.sh in this repository and no where clearly stated in the documentation as such

This seems clear to me (emphasis added):

This variable allows you to specify the name of a database to be used for creation scripts in /docker-entrypoint-initdb.d/*.js (see Initializing a fresh instance below). MongoDB is fundamentally designed for "create on first use", so if you do not insert data with your JavaScript files, then no database is created.

- source of docs from Docker Hub

@tianon has a PR for improving the user section: docker-library/docs#1418

[johnwyles]

@yosifkit Thank you for that response. Given the majority of developers are writing their code and initialization and configuration such that they assume (whether rightly or wrongly) that their database is there and a username and password they know is able to talk to and operate on it I think it would be a great addition to the image.

Given your excellently laid out example above I think this should be baked in and not putting onus on the users of this image to essentially all have copies of the script you mentioned running around in it's various permutations. What do you say to including it in the image:

• It solves the problems brought up in this issue
• It is backwards compatible
• It is an an entirely optional feature the way the script is written - if users want to they can include this MONGO_NON_ROOT_USERNAME and MONGO_NON_ROOT_PASSWORD if they like and get expected behavior and if they do not then nothing happens as expected as well

I think this is excellent if you were driving at building this into the image and see no reason not to since 99% of cases users will want a pre-initialized database with a username and password - putting this in documentation will help but having the extra step of them essentially copy/pasting your script so they can get what would be expected behavior of an image with an upstream project like this where the vast majority of developers and users are not having to write the database / username/password initialization into their code after connecting with a root role user. It also centralizes the location credentials can be kept and modified. Were it not for your example script other folks might have, understandably, done it like I did where I keep credentials in a .js file for the user database and MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD in docker-compose.yml (or k8s or whatever).

And of course simply adding your custom-user.sh code instead of in the /docker-entrypoint-initdb.d/ directory it would, of course, instead live alongside the rest in docker-entrypoint.sh.

[lonix1]

I understand the reluctance to add functionality to working software. I also understand @yosifkit's response, and I'm using his advice in my own code.

But this functionality is obvious and necessary - as evidenced by all those who complained about it in #174 and StackOverflow. We assumed it to work the way we've described, because that is the obvious need.

One of the reasons we use docker is the promise of "just spinning up" a new container that is ready for action. Extra steps and config (that exists in multiple places, and liable to fall out of sync) are an extra burden, which are easily avoided by the (backwards compatible) proposed additions.

[johnwyles]

I have submitted PR #331 as outlined by @yosifkit comments and code example as well taking into account his comments:

I'm mostly against adding more environment variables for creating a non-admin user, especially if it breaks backwards compatibility. We try to keep the images as close to upstream releases as possible with minimal maintenance and the entrypoint script is already very complex.

This does not break backwards compatibility and is a fully optional feature added for expected user behavior as itterated above by @lonix1 @johnwyles in this issue and numerous others in issue #174 (comment).

Combine that with automated builds (https://docs.docker.com/docker-hub/builds/) and repository links (https://docs.docker.com/docker-hub/builds/#repository-links) and it's reasonably easy to have an up-to-date image built FROM mongo with the custom non-root user creation modifications.

While more mature software projects will certainly require /docker-entrypoint-initdb.d/* files the image as it is out of the box is unusable without an extra step of gaining root access and performing the user and password creation on the DB that /docker-entrypoint-initdb.d/ operates against. In fact without a stanza in these files that creates a username and password then users would be left with the default behavior to use the root role to perform all operations. To me this is bad security prescribed by the approach of not having a non-root username and password set. Most users at the start of their projects and when they are in less maturity and without security conscious concerns would simply use this root user which is bad practice and an anti-pattern to be using this level of access.

And then I will just echo all the points in: #329 (comment)

• It solves the problems brought up in this issue
• It is backwards compatible
• It is an an entirely optional feature the way the script is written - if users want to they can include this MONGO_NON_ROOT_USERNAME and MONGO_NON_ROOT_PASSWORD if they like and get expected behavior and if they do not then nothing happens as expected as well

I will also put together a PR for the documentation update if we can proceed on this 👍

[johnwyles]

I have also added the documentation for this in PR docker-library/docs#1422 in the documentation as well.

[johnwyles]

BUMP What did we think about PR #331 and docker-library/docs#1422 to provide users with expected behavior, backwards compatibility, and optional parameters but that when present provide the expectation the user requires for database initialization? Let me know if the PR needs a bit of modification but the discussions here seem to have all been addressed in the PR and documentation PR that provide comfortably merging this in.

[prokhorovn]

Actually, I've posted a comment in a different issue, but it seems to be very mongo initialization process related, so that will leave it here also #323

#323 (comment)

To summarize: there are problems with MONGO_NON_ROOT_USERNAME and MONGO_NON_ROOT_PASSWORD when applying this variables to mongod instances in configsvr mode. Detailed description could be found by link above

[yosifkit]

@npiskunov, on your issue it looks like we just need to account for the default dbpath change for configsvr (#341).

---

On a related note, this also means that the PR for this issue(#331) has another edge case. The non-root user values cannot work when running as a config server since it cannot create a user outside of admin (or config).

When running with this option, clients (i.e. other cluster components) cannot write data to any database other than config and admin.

- https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-configsvr

Finding more edge cases like this is why I am so hesitant to add more environment variables.

---

Admittedly this means that, apart from #331, we might want to note that limitation for /docker-entrypoint-initdb.d/ scripts as well as MONGO_INITDB_DATABASE, but I haven't seen an issue about this, so it seems like a rare case.