Overview

Meteor Azure is a command line tool for deploying Meteor applications on Azure App Service.

The project is designed with an emphasis on simple configuration out-of-the-box, with extensive customisation for advanced usage.

Read the tutorial to get started, and report any issues or questions on our GitHub repo.

CLI Features

• Cross platform (macOS, Linux and Windows)
• One command deploy
• Load Meteor settings from file
• Auto-detect correct Node/NPM versions
• Track deployment progress in real-time
• Use custom web config

Azure platform benefits

• Auto-scaling
• Zero-downtime deployment
• High availability (with 99.95% SLA)
• 34 regions around the world
• Dedicated VMs
• Multi-core session affinity
• Configure advanced architectures (e.g multi-region failover)
• Security compliance (ISO, SOC and PCI)

Installation

Meteor Azure is available as an NPM package on Linux, macOS and Windows. You can choose to install globally or locally, depending on your requirements.

Prerequisites

• Node >=4 is necessary to run the CLI
• Meteor >=1.4 is necessary to build your application (along with a basic compiler toolchain if you have binary dependencies)

Global usage

Installing globally will make the tool available to any project on your machine. While this is convenient, it comes at the expense of portability and less control over versioning.

$ npm install -g meteor-azure

After installation, simply run meteor-azure from any command line to start using it.

Local usage

Installing locally will make the tool available to your current project. This is particularly useful when you want to automate deployments for an external process (e.g continuous integration).

$ npm install meteor-azure --save-dev

After installation, you can start using it by running ./node_modules/.bin/meteor-azure in the project directory or adding a script to your package.json file:

{
  "name": "my-project",
  "scripts": {
    "deploy": "meteor-azure"
  }
}

Getting started

Once you’ve installed Meteor Azure on your machine, this tutorial will run you through the basic setup and configuration of a new project.

Step 1: Create Azure Web App

If you don’t already have a Web App in Azure, you can create one using the portal:

Note

We do not support the Linux preview

Step 2: Configure Azure Web App

In the portal, navigate to your Web App and open “Application Settings”.

Ensure “Web sockets” and “ARR affinity” are enabled under “General Settings”, then clear any existing entries under “App settings”:

Open “Deployment credentials” and set a username and password (these are applicable to any app in your account):

Next, open “Overview” and record your app name, resource group and subscription ID:

If you have previously configured a deployment source for your app, open “Deployment options” and disconnect:

Activate the user drop-down and take note of the domain which appears under “Directory” (something.onmicrosoft.com), this is your tenant ID:

Step 3: Configure Meteor Azure

If your project doesn’t already have a Meteor.settings json file, create an empty one at the top-level (you can call it “settings.json”).

Open this file locally, and add a “meteor-azure” key with the following values:

{
  "meteor-azure": {
    "siteName": "app name",
    "resourceGroup": "resource group",
    "subscriptionId": "subscription ID",
    "tenantId": "tenant ID",
    "deploymentCreds": {
      "username": "username",
      "password": "password"
    },
    "envVariables": {
      "ROOT_URL": "https://<app name>.azurewebsites.net",
      "MONGO_URL": "MongoDB URL"
    },
  }

  // ... keys for Meteor.settings
}

Step 4: Deploy project

Navigate to the project directory on your local machine and run:

$ meteor-azure --settings path-to-settings-json

Your project should now be live at https://<app name>.azurewebsites.net

Next steps

• Setup HTTPS redirect (the “force-ssl” package is incompatible)
• Setup automatic CLI login
• Enable multi-core

Configuration

Meteor Azure is configured with a settings file and optionally, a custom web config.

Settings file

Your settings file contains Meteor.settings and the Azure Web App details.

It follows the format below:

Note

All fields are requires unless otherwise specified

{
  "meteor-azure": {
    "siteName": "",
    "resourceGroup": "",
    "subscriptionId": "",
    "deploymentCreds": {
      "username": "",
      "password": ""
    },

    // e.g "something.onmicrosoft.com"
    // (can be read from the user dropdown in the portal)
    "tenantId": "",

    "envVariables": {
      "MONGO_URL": "",

      // "https://<siteName>.azurewebsites.net" or a custom domain if you have set one
      "ROOT_URL": ""

      // ... other environment variables e.g MONGO_OPLOG_URL, MAIL_URL, etc.
    },

    // An optional field for selecting deployment slot
    // (see below for full instructions)
    "slotName": "",

    // An optional field for enabling non-interactive login
    // (see below for full instructions)
    "servicePrincipal": {
      "appId": "",
      "secret": ""
    }
  }

  // ... keys for Meteor.settings
}

Select deployment slot

To target a particular deployment slot, set the “slotName” field to the appropriate postfix and leave “siteName” as the base value.

For example: a deployment slot called “foo-bar-baz” where “foo-bar” is the base value and “baz” is the slot postfix, would have:

{
  "siteName": "foo-bar",
  "slotName": "baz"
  // ...
}

Setup automatic CLI login

In scenarios where an interactive login is inconvenient/prohibiting (e.g on a CI server), we can authenticate automatically by creating a service principal and granting resource access.

Follow the Azure instructions to configure this in the portal. Make sure to assign a “Contributor” role within the current subscription, and take note of your key value (which is the “secret”) and application ID.

Add these details to the “servicePrincipal” field and try running the CLI again. You should no longer be prompted for login.

Custom web config

The web config is used to configure your IIS web server in Azure. The default values provide a good starting point for most applications.

Some common use cases for a custom file (using the --web-config option) are described below.

We also have a repository of examples that you can browse through.

Setup HTTPS redirect

Note

We do not support the core ‘force-ssl’ package

To handle redirecting users to HTTPS, add an extra rewrite rule (preceding existing rules) and ensure your “ROOT_URL” is given with “https”:

<rewrite>
  <rules>
    <!-- Force HTTPS -->
    <rule name="Redirect to HTTPS" stopProcessing="true">
      <match url="(.*)" />
      <conditions>
        <add input="{HTTPS}" pattern="^OFF$" />
      </conditions>
      <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
    </rule>

    <!-- ... other rewrite rules -->
  </rules>
</rewrite>

Enable multi-core

To fully utilise CPU capacity on multi-core servers (offered by the larger instances), we can load balance between multiple processes of our application on each machine.

This is handled automatically by the IISNode module, and can be enabled by setting the “nodeProcessCountPerApplication” option:

<system.webServer>
  <!-- ... -->

  <!-- specify number of node processes to be started, setting this to 0
       will result in creating one process per each processor on the machine -->
  <iisnode nodeProcessCountPerApplication="0" />
</system.webServer>

Command line options

$ meteor-azure [options]

-h, –help	output usage information
-v, –version	output the version number
-s, –settings <path>	path to settings file [settings.json]
-w, –web-config <path>	path to custom web.config file
-d, –debug	enable debug mode
-q, –quiet	enable quite mode

Further reading

Meteor Azure combines and integrates a number of tools and services.

To help you understand and extend this architecture, we have compiled a list of important resources:

Azure platform

• Web Apps documentation
• Native CLI documentation
• Understand the basics of IISNode
• Access server admin/diagnostics with Kudu

MongoDB hosting

• Configure oplog
• mLab documentation
• Atlas documentation

Internal

• Repo for sample web config files
• Repo for server initialisation script