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 Amazon Elastic Container Service (ECS).

The rest of this guide assumes you are hosting on Amazon ECS. However, a Docker image is also publicly available at Quay if you would like to deploy the image in your own container or another service (view installation guide using Docker). Also, 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).

Part A. Get ready to self-host on Amazon ECS

Create an Amazon Web Services (AWS) account

Steps:

  1. Sign up for an AWS account if you don’t have one already.
  2. Follow AWS’ strong recommendation to securely lock away the credentials for the AWS account root user and create an Identity and Access Management (IAM) user that you log in with in order to configure and manage Amazon ECS.
    • The IAM user just needs “AWS Management Console access” and does not need “Programmatic access”.
    • You can use the out-of-the-box “AdministratorAccess” policy that AWS provides.

Prepare configuration variables

MLAB_DATA_API_KEY

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

MLAB_DATA_API_CONFIG

Steps:

  1. Log in to the mLab management portal
  2. Visit https://mlab.com/data-api-config
  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.

Part B. Launch the mLab Data API on Amazon ECS

Initiate the “Getting Started” wizard for Amazon ECS management

  1. Log in to the AWS management console with a user that has administrator access to ECS.
  2. Visit the ECS-specific area of the AWS management console.
  3. Ensure that the correct region has been selected
    • Select the region that your database(s) are running in in the drop-down menu on the upper-right hand side of the top navigation bar.
    • You will minimize network latency and instability by ensuring the mLab Data API is deployed in the same region as your database.
  4. Click on the blue “Get started” button.
    • If you end up on the “Clusters” page, click the grey “Get Started” button (and not the blue “Create Cluster” button).

Step 1. Configure the ECS Container and Task

img-container-env-variables

Key Value
MLAB_DATA_API_KEY Replace lorem-ipsum-dolor-sit-amet with the API key prepared in section A.
MLAB_DATA_API_CONFIG replace {"port": 8080, "clusters": {}, "databases": {}} the JSON config prepared in section A.

Step 2. Configure the ECS Service

Step 3. Configure the ECS Cluster

Step 4. Review and create the ECS Service

For more details see the installation guide for deploying the mLab Data API to Amazon ECS.

Step 5. Find the DNS name for the self-hosted mLab Data API

To make requests to the API, you’ll need the DNS address for the service.

Steps to find the DNS name:

  1. Visit the ECS-specific area of the AWS management console.
  2. Click on the name of the cluster, mlab-data-api-cluster.
  3. Click on the name of the service, mlab-data-api-container-service.
  4. Navigate to the Target Group by clicking on the link under “Target Group Name”.
  5. Navigate to the Load Balancer by clicking on the link to the right of the “Load balancer”.
  6. Copy the “DNS name” value.

Part C. Enable SSL on Amazon ECS (optional)

Part D. Test the 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 all of your mLab deployments through the new API.

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

Reconfigure your application to point to the new API. All you should need to change is 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.

APPENDIX 1 - Modifying the configuration of the running ECS Service