Guide to Self-Hosting the mLab Data API

You have a number of options available for self-hosting the mLab Data API.

For convenience and easy scalability, we recommend using Heroku.

The rest of this guide assumes you will use Heroku to host the mLab Data API. However, we also have published guide to deploying on Amazon Elastic Container Service (ECS) (view installation guide using ECS) and made a Docker image publicly available at Quay if you would like to deploy the image in your own container or another service (view installation guide using Docker). Finally, the mLab Data API is open-source if you wish to build and run it using some other method (view how to install using source code).


Docker CLI

Download and install Docker.

Heroku account

Create a Heroku account.

Install the Heroku CLI

Download and install the Heroku CLI.

Deploy the mLab Data API as a Heroku app

In the Heroku CLI steps below, replace the <APP> placeholder with the name of your Heroku app. A suggestion would be to call your Heroku app mongo-data-api-xxx where xxx is the name of your application or organization. Your self-hosted mLab Data API, when successully deployed, will then be accessible at

1. Log in to Heroku and Heroku Container Registry

% heroku login
% heroku container:login

2. Create a new Heroku app

% heroku create <APP>

3. Pull Docker image from public registry and push it to Heroku

docker pull
docker tag<APP>/web
docker push<APP>/web

4. Create a Heroku release

% heroku container:release web --app <APP>

5. Access the Heroku app and tail the log (error expected!)

Visit in your browser, replacing “nameofyourapp” with the name of your Heroku app.

Since we have not yet set the Heroku app’s configuration variables, we fully expect to see an error:


Tail the Heroku app’s log:

% heroku logs --tail --app <APP>

You should see that the process crashed with a “MLAB_DATA_API_CONFIG environment variable is required” log line.

Configure the Data API

Prepare two config vars


For convenience we suggest using the same API key that you are currently using. However, you may choose any key that you wish.



  1. Log in to the mLab management portal
  2. Visit
    • If you get a “Page Not Found” error that means that you are either logged into the wrong mLab account or you are not using the mLab Data API. If you are not using the mLab Data API, you do not need to self-host it.
  3. Copy the JSON document on this page.
    • This is a template for this configuration variable.
    • Everything in the template has been filled out except for the DBUSER and PASSWORD placeholders.
    • You only need to replace the database credential placeholders for the API endpoints that you’re actually using.
  4. For each Dedicated plan deployment that’s using the mLab Data API:
    • Replace the DBUSER and PASSWORD placeholders with valid database credentials.
    • You can use a “root” database user with the “admin” database in the URI (at minimum the dbAdminAnyDatabase privilege is required).
  5. For each Shared plan database that’s using the mLab Data API:
    • There will be two entries in the template - one using the /databases API endpoint, and one using the /clusters API endpoint. Check to see which endpoint your application is currently using.
    • Find the replace the DBUSER and PASSWORD placeholders with valid database credentials on the entry that your application is using.
    • You can use a normal, read/write database user.
  6. For each Sandbox database that’s using the mLab Data API:
    • Find the replace the DBUSER and PASSWORD placeholders with valid database credentials.
    • You can use a normal, read/write database user.

For more details view the documentation on these two required configuration variables.

Set Heroku app with config vars

You may set the Heroku app’s config vars using the Heroku CLI. However, we found that using Heroku’s web interface to configure these two config vars is easier than the CLI.

Visit<APP>/settings in your browser and then add three config vars.

Name Value
MLAB_DATA_API_KEY (use value prepared in step above)
MLAB_DATA_API_CONFIG (use value prepared in step above)
JAVA_OPTS -Djdk.tls.client.protocols=TLSv1.2

Whenever you add/modify a config var, your Heroku app will be automatically restarted with a new release that uses the updated value.

Having the JAVA_OPTS config var set to -Djdk.tls.client.protocols=TLSv1.2 will make it possible for you to connect to a MongoDB Atlas cluster but isn’t necessary when connecting to an mLab deployment that does not have TLS/SSL enabled.

Test your self-hosted mLab Data API

Once your self-hosted mLab Data API deployment is up and running, perform some tests against it to ensure that you can access your mLab deployments through the new API.

You should be able to simply change the base URL of the API (and the API key if you chose to use a different one). If you configured your new API deployment correctly, you should not need to change any other part of your application since all API URL paths should still be the same.

If the current URL used by your code looks like this:<MLAB_DATA_API_KEY config var value>

The new URL used by your code would look like this:

Reconfigure your application to use the self-hosted mLab Data API

Reconfigure your application to point to the new API. If you encounter any unexpected issues, you should be able to immediately roll back to the original URL.