Set Up Nightscout Using Heroku

3 Dec
Guides > Setup Guides > Set Up Nightscout Using Heroku

Heroku is currently the recommended platform for hosting your Nightscout site. You can run a single Nightscout site 24/7 with a free Heroku account.

The following directions will guide you through setting up a new Nightscout site on Heroku.

IMPORTANT NOTES:

  • If possible, go through this setup process on a desktop/laptop — many of the screens are harder to read and navigate on mobile devices. Also, these instructions are much easier to read on a larger screen.
  • For those familiar with Azure setups: Heroku automatically creates an mLab database for you during the setup process; you do not need to set up mLab separately. (If you want to use a different mLab database, you can replace the MONGODB_URI string in your Heroku config variables.)

To create your Nightscout website on Heroku:

  1. Create a GitHub account.
    • Choose the free plan. You can skip the survey questions in the second step.
    • Verify your account via the email they sent.
    • Once you’re verified and logged in, go to the main Nightscout repository here.
    • Make your own copy of the project by “forking” it: Click on the Fork button in the upper right.
    • After a moment, you will have your own fork of the project. Bookmark that page, as you’ll come back to it from time to time.
  2. Create a Heroku account.
    • Enter your account details. “Role” and “Primary development language” can be anything, but “Hobbyist” and “Node.js” are the most appropriate choices.
    • Verify your account via the link in the verification email, and set your password.
  3. Go to back to your GitHub account, and make sure you’re in your cgm-remote-monitor repository.
  4. In the repository, scroll down to where the Readme file is displayed, and click the purple Deploy to Heroku button.
    • Scroll down to where you see the full Readme displayed; do not click the README.md link in the file list. You’ll get a “No app.json located in the repo URL provided” error on deploying if you click the wrong purple button.
    • If you are doing this process on a phone or tablet, you may not see the Readme displayed on scrolling — have your browser load the Desktop version of the page first.
  5. On the Heroku screen that opens, fill in the information requested:
    • App name: Your site will have a URL like “yourappname.herokuapp.com”. This is where you choose the “yourappname” part.
    • Region: No matter where you are, this setting doesn’t impact you; can leave it on United States.
    • Config Vars: Most of these are populated with defaults that will be fine for a typical setup. All of them can be edited later on. There are a few you’ll want to note during this setup though:
      • API_SECRET: This is required. Enter a passphrase you will use for your site. It must be at least 12 characters. Be sure to write it down.
      • BG_HIGH, BG_LOW, BG_TARGET_TOP, and BG_TARGET_BOTTOM: The thresholds at which your site will alert you. HIGH and LOW are your “urgent” thresholds; TARGET_TOP and TARGET_BOTTOM are the top and bottom of your “good” range.
        • All of these values must be entered in mg/dl amounts, even if you use mmol/L. Multiply by 18 to convert — if you want a BG_TARGET_TOP of 10.0 mmol/L, enter “180” (10 x 18).
      • BRIDGE_PASSWORD and BRIDGE_USER_NAME: If your data is coming from the Dexcom Share service, you are making a “bridge”. Enter your Dexcom account name and password here — the same credentials you use to sign into the Dexcom app on the phone, and the Clarity service.
        • Make sure to also add the bridge plugin on the ENABLE line below.
        • If you are outside the US, you will need to also add another variable later in the setup process.
      • DISPLAY_UNITS: Units will be mg/dl by default. If you want mmol/L, enter just “mmol” here.
      • ENABLE: This is the variable that turns on all the features you want to use. There are many plugins available, and you can always add or remove them later.
        • This field must be just a list of plugin names separated by spaces. No quotation marks, commas, or anything else. 
        • A good starting set is:
          careportal basal
        • If you also want to track pump site changes and sensor changes:
          careportal basal cage sage
        • If you’re doing a Dexcom Share bridge:
          careportal basal bridge
        • There’s a list of most of the plugins and what they do here.
      • MONGO_COLLECTION: This field is required, but should remain as-is (as “entries”).
      • THEME: If you want your BG graph to be green/yellow/red as it moves across the thresholds, change this to colors.
  6. Click the Deploy app button at the bottom of the page.
    • Heroku will begin deployment, going through a list of automated steps at the bottom of the page.
    • During the “Configure environment” step, you will be asked to add a credit card to the account. All Heroku accounts need a credit card on file to verify the account and allow for paid add-ons. You will never be charged without explicitly opting in to extra levels of service, and for a typical Nightscout site you won’t ever need anything extra.
    • After adding your card, you’ll be back at the deployment page. Click the Deploy app button again, and it’ll complete this time.
      Be patient. This can take a few minutes.
  7. Once it has successfully deployed, click the View button to open your new site.
  8. You will get a warning message about your profile — it just needs to be set up. Continue to the Profile Editor page.
    • Find the Timezone picker, and choose your zone. Make sure not to pick one of the generic zones (like “PST”), but rather one with a country or region prefix (like “Canada/Pacific”).
    • You can make other changes on this page now if you want, but you don’t need to.
    • You can’t save your changes yet — click the Authenticate link at the bottom, and enter your API_SECRET from before. (Check the “Store hash on this computer” box if you want it to remember your authentication and not ask again.)
    • Now click the Save button. You might get a warning message about the profile format, which you can ignore.
    • Now go back to your main Nightscout page by typing in your site URL into the address bar. Your URL is the App name you chose earlier, plus “.herokuapp.com” (yourappname.herokuapp.com).
  9. If you are using a Dexcom Share bridge, note the additional steps below.

Configuring the site

To make additions or changes to any of your settings, go to your Heroku dashboard. Go into your app, go to the  “Settings” section, and then click the “Reveal Config Vars” button to show all the site variables. Bookmark your app’s Settings page; you’ll likely come back to it often to make changes.

Bridge Users

In order for your site to stay active 24/7, you’ll need to set up a free Uptime Robot (the constant pings from this status-checking service will keep your Nightscout app awake).

  • Create a new account, and verify it with the email you get.
  • Log in, and click the + Add New Monitor button.
  • Choose HTTP(s) for the Monitor Type, pick any Friendly Name, and enter your site URL as the URL (http://yourappname.herokuapp.com). Leave the rest as-is, and click Create Monitor.

Important note: In order for the bridge to work, you need to have Sharing active in your Dexcom app on the T1’s phone. You do not need to have any followers.

If you are outside the US, you also need to add one more variable to your Heroku setup:

  1. Get to your Heroku Config Vars list as described above.
  2. Scroll to the bottom of the list, and add a new line, with BRIDGE_SERVER as the KEY, and EU as the VALUE:You don’t need to do anything else after adding that — in a few minutes, your Nightscout page should start showing your BG data.

Deploying a different branch

If (at any point) you need to deploy a different branch to your existing Heroku site:

  1. Click the “Manage App” button (or navigate to your app from the dashboard)
  2. Click the “Deploy” tab.
  3. If your app shows that it is connected to GitHub:
    • At the bottom of the screen, under the heading “Deploy a GitHub branch,” select the branch (e.g., “dev”) from the drop-down list.
    • Click “Deploy Branch.”
    • Wait for the deployment to fully finish, and try to view the app (use the button or open your Heroku url in another browser tab).
  4. If your app doesn’t appear to be connected to Github:
    • Click “GitHub” next to “Deployment Method.”
    • Enter your GitHub user name in the first box next to “Connect to GitHub” and enter “cgm-remote-monitor” in the next box.
    • Click “Search.”
    • Select your repository and click “Connect.”
    • At the bottom of the screen, under the heading “Deploy a GitHub branch,” select the branch (e.g., “dev”) from the drop-down list.
    • Click “Deploy Branch.”
    • Wait for the deployment to fully finish, and try to view the app (use the button or open your Heroku url in another browser tab).

Configuring Your Uploader

Depending on your uploader app, you may need to configure the app to use REST API for uploading data to your Nightscout site. The sample syntax shown in your app may show the format for an Azure site. A Heroku site takes this format:

https://YOURSECRET1234@YOURSITENAME.herokuapp.com/api/v1