6. Serving with MongoDB¶
Nemesyst uses MongoDB as its primary message passing interface. This page will more elaborate on using Nemesyst with different database setups, debugging, common issues, and any nitty-gritty details that may be necessary to discuss.
Warning
While Nemesyst does support using mongodb.yaml files for complex db setup, care should be taken that Nemesyst is not overriding the values you were expecting in the config files. Things such as the DBs path are almost always overridden along with the port to use by default even if the user has not provided that argument. In future we intend to make it such that hard coded defaults when not overridden by the user, first attempt to look in the mongodb.yaml file before falling back to hard-coded values.
6.1. Creating a basic database¶
Disambiguation: we define a basic database as a standalone MongoDB instance with one universal administrator and one read/write user with password authentication.
While it is possible it is highly discouraged to use Nemesyst to create the users you require as this is quite complicated to manage and may lead to more problems than its worth compared to simply creating a database and adding a user manually using something like the following:
6.1.1. Manual creation of MongoDB¶
- Files-only/ development creation of database example:
mongod --config ./examples/configs/basic_mongo_config.yaml
This will create a database with all the MongoDB defaults as it is an empty yaml file.
If you would instead want a more complex setup please take a look at examples/configs/authenticated_replicaset.yaml instead, but you will need to generate certificates and keys for this so it is probably a poor place to start but will be what you will want to use in production as a bare minimum security.
6.1.2. Docker-Compose creation of MongoDB¶
- Docker-Compose, Files-only/ development creation of database example:
docker-compose up
This similar to the Manual creation of MongoDB creation uses a simple config file to launch the database. This can be changed in docker-compose.yaml.
At this point you will need to connect to the running MongoDB instance (see: Connecting to a running database) to create your main administrator user, with “userAdminAnyDatabase” role.
After this you can use the following to close the Docker container with the database:
- Docker-Compose, Files-only/ development, closing Docker-Compose database example:
docker-compose down
Note
Don’t worry we set our docker-compose.yaml to save its files in /data/db so they are persistent between runs of docker-compose. If you need to delete the MongoDB database that is where you can find them.
6.1.3. Connecting to a running database¶
To be able to fine tune, create users, update etc it will be necessary to connect to MongoDB in one form or another. Nemesyst can help you log in or you can do it manually.
Note
If there is no userAdmin or userAdminAnyDatabase then unless expressly configured there will be a localhost exception which will allow you to log in and create this user. If this user exists the localhost exception will close. Please ensure you configure this user as they can grant any role or rights to anyone and would be a major security concern along with making it very difficult to admin your database.
6.1.3.1. Nemesyst¶
Nemesyst can be used to log you in to the mongo shell although this feature should not be depended on, and instead it is recommended to use mongo for anything more complicated than simple testing. You will need to provide any other options like ip port etc if it is not using the defaults.
- Bash shell simple all defaults example:
nemesyst --db-login
6.1.3.2. Mongo¶
To connect to an non-sharded database with autnentication but no TLS/SSL:
- Bash shell example:
mongo HOSTNAME:PORT -u USERNAME --authenticationDatabase DATABASENAME
To connect to a slightly more complicated scenario with authentication, TLS, and sharding enabled:
- Bash shell example:
mongo HOSTNAME:PORT -u USERNAME --authenticationDatabase DATABASENAME --tls --tlsCAFile PATHTOCAFILE --tlsCertificateKeyFile PATHTOCERTKEYFILE
6.1.4. Creating database users¶
You will absolutely need a user with at least “userAdminAnyDatabase” role. Connect to the running database see Connecting to a running database.
- Mongo shell create a new role-less user:
db.createUser({user: "USERNAME", pwd: passwordPrompt(), roles: []})
- Mongo shell grant role to existing user example:
db.grantRolesToUser( "USERNAME", [ { role: "userAdminAnyDatabase", db: "admin" } ])
- Mongo shell create user and grant userAdminAnyDatabase in one:
db.createUser({user: "USERNAME", pwd: passwordPrompt(), roles: [{role:"userAdminAnyDatabase", db: "admin"}]})
Note
Since this user belongs to admin in the previous examples that means the authenticationDatabase is admin when authenticating as this user as per the instructions in “Connecting to a running database”.
6.2. From basic database to replica sets¶
- todo
Include instructions for turning a database into several replica sets.
6.3. Troubleshooting¶
Please see MongoDB/ Serving Issues