Docs Menu

Install MongoDB Charts

On this page

  • System Requirements
  • Before You Install
  • Install MongoDB Charts
  • Troubleshooting

The following document describes how to install MongoDB Charts within your environment. To upgrade MongoDB Charts from an older version, see Upgrade MongoDB Charts.

MongoDB Charts requires a MongoDB deployment running version 3.6 or later to store Charts metadata. The Charts metadata cluster can run MongoDB Atlas, the cloud-hosted service for running, monitoring, and maintaining MongoDB deployments.

Note

Charts does not require its own dedicated MongoDB deployment. If Charts uses an existing MongoDB deployment, it will create and use the following databases:

  • app,
  • auth,
  • events,
  • hosting,
  • log,
  • metadata.

MongoDB Charts must be installed on a single server running Docker CE or EE (v17.06 or higher). The server must be in a network location that can communicate with the metadata database and MongoDB servers that contain the data you wish to visualize.

End users accessing MongoDB Charts must use a current desktop version of Chrome, Firefox, or Safari on any operating system.

1

MongoDB Charts requires a MongoDB database to store Charts users, dashboards, data sources, etc. Identify or configure a MongoDB deployment to store Charts metadata. For a production deployment, deploy MongoDB in a three member replica set and enable authentication.

The connection URI of this deployment is required in a later step.

2

MongoDB Charts runs within a Docker Linux container. Install Docker CE or EE (v17.06 or higher) on the Charts host. Charts runs on any OS or distribution supported by Docker, including Windows and macOS.

1

From your command prompt, create a directory to store your Charts configuration, then change to the new directory:

mkdir mongodb-charts
cd mongodb-charts
2

Download the latest version of the Charts Docker Compose file from the MongoDB Download Center and manually move it to the new directory.

3

Run the following command to enable Docker Swarm mode:

docker swarm init
4
docker pull quay.io/mongodb/charts:19.12.2
Note

If you are using a different version of Charts, replace 19.12.2 with the version number of your release.

This command may take a while as it downloads a large file to the host server.

5

MongoDB Charts requires a Connection String URI to connect to a MongoDB deployment which will store the Charts metadata. The deployment must be reachable from the Charts host. If the deployment is running with authentication enabled, you must provide the credentials in the connection string, and the authenticating MongoDB user must have the readWriteAnyDatabase role.

The connection string URI you provide depends on the configuration of your MongoDB deployment. Your deployment can be:

  • A standalone deployment running on the same host as your Charts instance.
  • A standalone deployment running on a different host than your Charts instance.
  • A replica set deployment running on a multiple hosts external to your Charts instance.
Note

For a production deployment, your metadata database should be a three member replica set with authentication enabled.

Select the appropriate tab for your deployment configuration:

Note

If you are using a different version of Charts, replace 19.12.2 with the version number of your release.

If the MongoDB Charts successfully connects to the specified MongoDB deployment, Charts displays the following message in the command line:

MongoDB connection URI successfully verified.

Pay careful attention to the output of this command, as it may include warnings of potential issues which could impact the deployment process.

If MongoDB Charts cannot connect using the specified connection URI, Charts outlines possible troubleshooting actions to take to create a successful connection. For detailed troubleshooting information, refer to the Troubleshooting section.

6

Once you have verified that MongoDB Charts can successfully connect to your MongoDB deployment, create a Docker secret to hold the Connection String URI.

Run the following command to create the Docker secret, substituting your connection string from the previous step:

echo "<Verified connection string URI from step 5>" | docker secret create charts-mongodb-uri -
Note

If you are using a different orchestrator to run MongoDB Charts, such as Kubernetes, you may need to provide the MongoDB URI using an environment variable instead of a Docker secret. If you configure the CHARTS_MONGODB_URI environment variable within the container, this variable directs Charts to use this value for the connection instead of using the Docker secret. How you specify the environment variable depends on your chosen method for deploying the Charts Docker container.

7

MongoDB Charts includes a widget on every page that allows users to request assistance or provide feedback to MongoDB. It also enables the transmission of usage statistics to MongoDB to help improve the product. These statistics include:

  • Operations performed
  • Chart types created
  • Errors that MongoDB Charts returns

Charts sends the logged-in user's email and name to the Intercom system to help provide support. No data is collected or transmitted from the user's databases.

By default, the Feedback and Support widget is enabled.

To disable the widget within MongoDB MongoDB Charts and prevent the transmission of usage statistics:

  1. Open charts-docker-swarm-<version>.yml.
  2. Set the following value:

    CHARTS_SUPPORT_WIDGET_AND_METRICS: "off"
  3. Restart MongoDB Charts.

To re-enable the widget

  1. Open charts-docker-swarm-<version>.yml.
  2. Set the following value:

    CHARTS_SUPPORT_WIDGET_AND_METRICS: "on"
  3. Restart MongoDB Charts.
8

You can either run MongoDB Charts using the default HTTP protocol, or configure the Charts web server to use the HTTPS protocol for additional security. For instructions on configuring HTTPS for MongoDB Charts, see Configure MongoDB Charts Web Server to Use HTTPS.

9

Launch the Charts container as a Docker Stack using the Compose file:

docker stack deploy -c charts-docker-swarm-19.12.2.yml mongodb-charts
Note

If you are using a different version of Charts, replace 19.12.2 with the version number of your release.

10

Check that the container is running by executing:

docker service ls

The Charts container should appear with mode replicated with 1/1 replicas:

ID NAME MODE REPLICAS IMAGE PORTS
j77uo3slyg4l mongodb-charts_charts replicated 1/1 mongodb-charts:latest *:80->80/tcp
Note

The service's mode may not be replicated immediately. Docker does not display the status of certain deployment operations, so wait briefly then rerun docker service ls.

If the service is stuck at 0/1 replicas and it's mode is not replicated after an extended period of time, the service may not have deployed properly. For more information, see Troubleshooting.

11

Once the container is running, execute the charts-cli add-user script within the container once for each Charts user account you want to create within MongoDB Charts. At minimum, you must use the script to create one user with the UserAdmin role in order to be able to log into Charts. After creating this initial user, you can either use the Charts user interface to add users or continue using the charts-cli add-user script to add users with either the UserAdmin or User role.

To add users with the script, run the following command. Replace the placeholders in angle brackets with the appropriate values.

For more information on roles and adding users, see User Management.

12

Access MongoDB Charts by opening a web browser and connecting to the name of the server running the container. Note that Charts runs on HTTP port 80 and HTTPS port 443 (if configured for HTTPS) unless you have modified the Docker Compose file to use different ports.

13

MongoDB Charts uses a number of keys and tokens to secure your deployment and encrypt sensitive data stored in the Charts metadata database. When you first deploy Charts, new random keys are automatically generated and saved to a Docker volume which persists the keys across container deployments.

Important

If you want to redeploy Charts or move Charts to a new server, you will need to use the original keys in new deployments. If you deploy a new instance of Charts and point it to an existing Charts metadata database used by a previous deployment, the encryption keys will not match and the new instance of Charts will not be able to decrypt the metadata.

To back up the keys, use the following commands to launch a temporary container that copies the key files from the Charts volume to a newly created directory on the host system:

Important

Once the operation above completes, store the key in a secure location that is not on the Charts server.

For more information, see Back Up and Restore Security Keys.

If MongoDB Charts does not successfully load in a browser after starting the Docker stack, try the following steps:

1

Check that the container is running by executing:

docker service ls

The Charts container should appear with mode replicated with 1/1 replicas:

ID NAME MODE REPLICAS IMAGE PORTS
j77uo3slyg4l mongodb-charts_charts replicated 1/1 mongodb-charts:latest *:80->80/tcp

Proceed to the next step if any of the following conditions are met:

  • The service is stuck at 0/1 replicas and its mode is not replicated after an extended period of time. This may indicate that the service did not deploy properly.
  • If you receive errors when running the charts-cli add-user script.
  • The Charts application is not loading in your web browser.
2

Retrieve the service logs by running the following command using the service ID from the previous step:

docker service logs <service ID>

The following example contains sample output from the command. Note each step has a tick or cross which could explain the issue:

mongodb-charts_charts.1.nzcj90stcbmz@linuxkit-00155d01851f | ✔ encryptionKeyPath
mongodb-charts_charts.1.nzcj90stcbmz@linuxkit-00155d01851f | ✔ stitchConfigTemplate
mongodb-charts_charts.1.nzcj90stcbmz@linuxkit-00155d01851f | ✔ tokens
mongodb-charts_charts.1.nzcj90stcbmz@linuxkit-00155d01851f | ✔ stitchConfig
mongodb-charts_charts.1.nzcj90stcbmz@linuxkit-00155d01851f | ✔ stitchConfigWritten (true)
mongodb-charts_charts.1.nzcj90stcbmz@linuxkit-00155d01851f | ✖
mongoDBReachable failure: Can't connect to MongoDB at mongodb://mongod. Too many
failed attempts. Last error: failed to connect to server [mongod:27017] on first
connect [MongoNetworkError: getaddrinfo ENOTFOUND mongod mongod:27017]
3

Deleting and redeploying the Docker stack may help solve common installation issues. Run the following command to remove Charts from the Docker stack:

docker stack rm mongodb-charts
4

Malformed Connection String URIs commonly cause issues when deploying Charts. To modify the URI, you must remove the old Docker secret:

docker secret rm charts-mongodb-uri

Then recreate the secret:

echo "mongodb://<username>:<password>@myhost.com/" | docker secret create charts-mongodb-uri -

To learn how to properly format your secret command, see steps 5 and 6 in the installation procedure.

5

You can now redeploy the Docker stack using the new secret.

Before redeploying, you need to ensure that the Charts containers are fully shut down. You can confirm this by running the docker ps command several times, until it shows no running Charts containers.

Once all Charts containers have shut down, relaunch the stack using the following command:

docker stack deploy -c charts-docker-swarm-19.12.2.yml mongodb-charts
Note

If you are using a different version of Charts, replace 19.12.2 with the version number of your release.

6

If you still have trouble accessing the Charts application, copy the logs from step 2 this procedure and contact MongoDB Support via the chat button within the MongoDB Charts application.

Note

The chat feature is not available when the Feedback and Support widget is disabled.

You can also submit a post describing your issue to the MongoDB Community Forum to discuss the issue with other members of the MongoDB Community.

You may encounter issues connecting MongoDB Charts to a MongoDB deployment if the MongoDB deployment uses hostnames which are not routable inside the Docker container. In this case, specify the extra_hosts option in the Docker Compose file downloaded in step 2 of the install procedure to manually map the hosts to your Docker container:

services:
charts:
# Other settings will be set here
extra_hosts:
- "somehost:198.51.100.16"
- "otherhost:198.51.100.17"
- "anotherhost:203.0.113.0"
Note

When manually mapping to a replica set, you must specify host entries for each replica set member, not just those in the connection string URI.

Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.