Guide to Migrating a Nightscout Sandbox Heroku Add-on to Atlas

This migration guide from mLab to Atlas is appropriate for users with a Nightscout setup on Heroku that was configured via the “Deploy to Heroku” button (see docs). We also have a demo video for Nightscout users.

If your Nightscout app is hosted on Azure or you moved it from Azure to Heroku, please email support@mlab.com for help and do not proceed.

For all other users, please see our FAQ on how to migrate.

Migration Prerequisites

  1. Update your Nightscout site to at least 14.0.1. To confirm that your Nightscout app is running 14.0.1 or higher:
    • Visit https://nameofyourapp.herokuapp.com (replace “nameofyourapp” with the name of your Heroku app).
    • Click on the icon with 3 horizontal bars on the top-righthand corner of the page. This will open a pane on the right side of the page.
    • At the bottom of the panel you’ll see an “About” section. Confirm that you see version 14.0.1 (or higher): img-nightscout-app-about.
  2. Update your automated insulin delivery system (Loop, OpenAPS/oref0, AndroidAPS, etc.) to the latest released version or use a recent development branch of the software.

  3. Be aware that unlike mLab, the Atlas M0 (free) tier does not include backups. If backups are important to you, you will need to manually take your own backups (email support@mlab.com for help) or migrate to the Atlas M2 tier which is approximately $9 per month and includes a free daily backup.

Pre-Migration Setup

A. Create your Atlas organization

  1. Visit https://mongodb.com/cloud/atlas/signup and register for an Atlas account.
    • The email address that you sign up with will become the username that you use to log in.
  2. Ensure that you are on the Project view by visiting https://cloud.mongodb.com.
  3. (Optional) Rename the default organization.
    • Rename it to your name or your family name (e.g., “Smith Family”).
    • You will be able to change this later so don’t worry about what you choose.
  4. (Optional) Delete the Atlas project that was automatically created during registration.
    • An Atlas project called “Project0” was automatically created in Step 1 and can optionally be deleted since it won’t be used.

B. Connect your Atlas organization to the source mLab account

In order to use the migration tool that was custom-built for migrations from mLab to Atlas, you’ll need to create a connection between your mLab account and your new Atlas organization.

When you created your mLab Heroku add-on, that process automatically created an account at mLab for you with an account name prefixed with “heroku_”.

Steps:

  1. Ensure that you are logged in to the target Atlas organization.
  2. Ensure that the target Atlas organization has been selected from the Organizations menu (the drop-down menu in the top-left corner next to the MongoDB green leaf logo).
  3. Click on the Organization Settings icon next to the Organizations menu (the gears icon). img-atlas-org-settings.
  4. Click on the green “Connect to mLab” button.

  5. Log in to the source mLab account from the same browser.
  6. In mLab’s UI review the text presented by the “Authorize MongoDB Atlas” form and click “Authorize” to complete the connecting of your mLab account with your Atlas organization.
  7. The “mLab Account” link in the left navigation pane should now be highlighted, and you should see the “mLab Account” view which provides access to the migration wizard.
  8. Make sure that deployment listed includes “heroku_” in it (e.g., ds123456/heroku_b4k80p49).
    • If it does not, you are either running Nightscout on mLab directly (not via Heroku) or you must have multiple mLab accounts, and you’ve connected to the wrong one.

If you’ve navigated away from this “mLab Account” view you can return back at any time by navigating to the Organization Home view (click on the green MongoDB leaf icon in the upper-left corner) and then clicking on the “mLab Account” link.

Migrating a Specific Database

After reviewing the migration prerequisites detailed above and completing the pre-migration setup steps, perform the following steps to migrate your mLab Sandbox database.

C. Initiate the migration process

Steps:

  1. Ensure that you are on the “mLab Account” view and seeing a list of your mLab deployment(s). If you are not on this view:
    • Ensure that you are logged in to the target Atlas organization.
    • Ensure that the target Atlas organization has been selected from the Organizations menu (the drop-down menu in the top-left corner next to the MongoDB green leaf logo).
    • Navigate to the Organization Home view (click on the green MongoDB leaf icon in the upper-left corner).
    • From the left navigation select “mLab Account”.
  2. Locate the mLab Sandbox deployment that you want to migrate to Atlas.
    • Click the ellipses (…) button for that deployment.
    • Click “Configure Migration” to open the migration wizard for the given deployment.

Below is a screenshot example of what the migration wizard looks like in the Atlas UI when migrating from an mLab Sandbox database to an Atlas M0 cluster.

img-screenshot-heroku-sandbox-checklist

D. Complete the tasks in the migration wizard

Step 1. Create the target Atlas project

Enter a value in the “Project Name” field (e.g., “nightscout”) and then click on the green “Confirm Project and Continue” button. You will be able to change the name of the project later.

img-screenshot-heroku-sandbox-create-project `

Step 2. Import database user(s)

Click on the green “Import Database Users and Continue” button.

img-screenshot-heroku-sandbox-db-users

Step 3. Configure an IP whitelist

Check the checkbox to allow all IP addresses and then click on the green “Allow All and Continue” button.

You will receive an email from MongoDB Atlas with subject of ‘You’ve added “Allow access from anywhere (0.0.0.0/0)” to your IP Whitelist’. This is expected.

img-screenshot-heroku-sandbox-whitelist

Step 4. Create the target Atlas cluster

Select “Create most equivalent new cluster” from the drop-down menu. This will expand the modal into a larger screen.

Scroll down and click the green “Confirm Target and Continue” button to create a free Atlas database (M0 tier). It will take about 7-9 minutes for the Atlas database to be created.

Unlike mLab, the Atlas M0 (free) tier does not include backups. If backups are important to you, you will need to manually take your own backups (email support@mlab.com for help) or migrate to the Atlas M2 tier which is approximately $9 per month and includes a free daily backup.

img-screenshot-heroku-sandbox-cluster

Step 5. Confirm the source and target

Review info about the source and target to confirm that you’re migrating from and to the correct deployments. If everything looks good, click on the green “Confirm and Continue” button.

img-screenshot-heroku-sandbox-confirm

Step 6. Test the migration

Click on the green “Begin Test Run” button.

Note that:

img-screenshot-heroku-sandbox-test-migration

Step 7. Test connectivity

Assuming you have reviewed the Migration Prerequisites, you can skip the instructions in this step and click on the green “Confirm and Continue” button.

img-screenshot-heroku-sandbox-test-connectivity

Step 8. Ensure independence from the Heroku add-on’s config var

Nightscout users can skip this step completely because the Nightscout code already looks for the existence of a different config var, MONGO_CONNECTION, which we will be creating later. Click on “Confirm and Continue”.

img-screenshot-heroku-sandbox-config-var

Step 9. Migrate

This step is the real migration! Clicking “Begin Migration” will change the role of the database user(s) which exist on the source mLab deployment to be read-only.

If an unexpected error occurs, and you want to abort the migration process and start using your source mLab deployment again, you will need to recreate the database user(s) on your source mLab deployment through mLab’s management portal. Performing a test migration ahead of time will help avoid the need to do this.

If you do rollback to mLab, note that any writes that are made to the target Atlas cluster will not exist on the source mLab deployment and will be deleted if you attempt another migration later. You should not start another migration; instead please email support@mlab.com with a link to your Atlas organization or project for help.

img-screenshot-heroku-sandbox-migrate

Step 10. Start using Atlas

At this point the import of data and indexes from your source mLab database to the target Atlas cluster is complete.

You can now restart your Nightscout application with the connection string for your Atlas cluster:

  1. Click on the “Copy” button to copy the connection string to your Atlas cluster into a text editor. img-screenshot-heroku-sandbox-start-using-atlas
  2. Log in to Heroku.
  3. In the Heroku UI, you should see your Nightscout app listed. Click on the row for your Nightscout app to navigate to its management page.
  4. In the Heroku UI, select the “Settings” tab.
  5. In the Heroku UI in the “Config Vars” section, click on the “Reveal Config Vars” button. img-heroku-reveal-config-vars-button
  6. In the Heroku UI, find the config var named either “MONGODB_URI” or “MONGOLAB_URI”. Copy the characters in between the “:” character and the “@” character. Those characters make up the database user’s password. In your text editor, replace the <password> placeholder with this password. You now have prepared the Atlas connection string in your text editor.
    • Make sure you have not inadvertently added a space before or after the password. The connection string should not have any spaces in it.
    • Make sure you do not include the “<” and “>” characters from the password placeholder since those are simply signifying a placeholder value.
  7. In the Heroku UI at the bottom of the list of config vars, add a brand-new MONGO_CONNECTION config var with the connection string to your Atlas cluster.
  8. Verify that your Nightscout app is still working. If it is not working, do not start another migration since this will make things worse. Instead, see the Troubleshooting section below.

Step 11. Delete mLab deployment (instructions only)

To delete the source mLab deployment, you will need to delete the Heroku mLab add-on via Heroku’s interface. Once you’ve deleted the add-on, verify again that your Nightscout app is still working.

Troubleshooting

Q. I am seeing a “Wrong API secret” message after completing Step 10 (Start Using Atlas). What do I do?

This most likely means that you have multiple mLab databases, and you migrated the wrong one. However, this error can occur for a number of other reasons - please see the last question on this page on how to get help.

Q. I am seeing “Error: invalid schema, expected mongodb” after Step 10. What do I do?

This means that you did not update your Nightscout site to the latest version (Step 1 of the Migration Prerequisites).

If you did update to the latest Nightscout version, please double-check that you completed Step 12 (the last step) of these version update instructions. This step is important because it will ensure that you have deployed the updated Nightscout version to your Heroku Nightscout application.

Steps to confirm which Nightscout version your app is running:

  1. Navigate to https://dashboard.heroku.com/apps/nameofyourapp (replace “nameofyourapp” with the name of your Heroku app).
  2. Click on the “More” button at the upper-right corner and select “Run console”.
  3. From the form that slides up, click on the “bash” link in blue below the “Run” button and then click on the “Run” button.
  4. Once you see the “~ $” prompt, carefully type in “npm ls | grep nightscout” like so:
~ $ npm ls | grep nightscout

… then press on the return/enter button on our keyboard. The response will include a string like:

nightscout@13.0.1  / app

In this example, the version of Nightscout deployed to your app is 13.0.1.

Q. My Nightscout app isn’t working after Step 10. What do I do?

  1. Do not start another migration as this will make things worse.
  2. If you haven’t already, update your Nightscout site to the latest version (Step 1 of the Migration Prerequisites).
  3. Ensure that the value of the MONGO_CONNECTION config var does not have any spaces in it. This value should start with “mongodb+srv://” if you completed Step 10.
    • If you find an issue and fix it, wait a minute to see if your app at https://nameofyourapp.herokuapp.com is now working for you (replace “nameofyourapp” with the name of your Heroku app).
  4. Ensure that “MONGO_CONNECTION” is spelled correctly (i.e., no typos).
    • If you find an issue and fix it, wait a minute to see if your app at https://nameofyourapp.herokuapp.com is now working for you (replace “nameofyourapp” with the name of your Heroku app).
  5. Reset the database user’s password by visiting the “Database Users” view for your Atlas project and click on the “EDIT” button to change the database user’s password. Then replace the password placeholder (<password>) in the MONGO_CONNECTION config var with the new password.

For more help, see the next question.

Q. How do I get help?

The mLab Support team is here to help! Please email support@mlab.com with:

  1. A link to your Atlas UI after you are logged in; the link should include “cloud.mongodb.com”.
  2. The value of the “MONGO_CONNECTION” config var (mask the database password by replacing the text between the “:” and the “@” with “PASSWORD”).
  3. A link to your Nightscout app; the link should include “herokuapp.com”.