This article will walk you through deploying your Meteor app to a AKLWEB HOST VPS running Ubuntu 14.04. It may also work on other Linux distributions (attempt at your own risk).

An ingenious fellow named Arunoda Susiripala, who’s quite active in the Meteor community, has developed a deployment tool called mupx (short for “Meteor Up X”), which makes it extremely easy to deploy your Meteor application to a remote server via ssh. Mupx is the successor to mup. We’ll walk you through the process from start to finish. Mup does most of the heavy lifting, fortunately, so this will be a breeze!

Our first step is to install mupx. You’ll do this on your development workstation, not your VPS server! Make sure you have Node.js already installed, and run:

$ npm install -g mupx

After installation is complete, go into your Meteor project folder, e.g. /projects/myApp, and run the following commands:

$ mkdir .deploy
$ cd $_
$ mupx init

For those not familiar with the $_ syntax, it’s a shortcut for the last argument used in a command. So in this case, cd $_ executes as cd .deploy.

You will see the following output:

Meteor Up: Production Quality Meteor Deployments
------------------------------------------------
Configuration file : mup.json
Settings file      : settings.json

Empty Project Initialized!

The initialization process creates two files, mup.json and settings.json. We’ll leave the latter file alone right now. Go ahead and open up mup.json. At the time of writing this article, the default mup.json looks like this:

{
  // Server authentication info
  "servers": [
    {
      "host": "hostname",
      "username": "root",
      "password": "password",
      // or pem file (ssh based authentication)
      // WARNING: Keys protected by a passphrase are not supported
      //"pem": "~/.ssh/id_rsa"
      // Also, for non-standard ssh port use this
      //"sshOptions": { "port" : 49154 },
      // server specific environment variables
      "env": {}
    }
  ],

  // Install MongoDB on the server. Does not destroy the local MongoDB on future setups
  "setupMongo": true,

  // Application name (no spaces).
  "appName": "meteor",

  // Location of app (local directory). This can reference '~' as the users home directory.
  // i.e., "app": "~/Meteor/my-app",
  // This is the same as the line below.
  "app": "/path/to/the/app",

  // Configure environment
  // ROOT_URL must be set to your correct domain (https or http)
  "env": {
    "PORT": 80,
    "ROOT_URL": "http://myapp.com"
  },

  // Meteor Up checks if the app comes online just after the deployment.
  // Before mup checks that, it will wait for the number of seconds configured below.
  "deployCheckWaitTime": 15,

  // show a progress bar while uploading. 
  // Make it false when you deploy using a CI box.
  "enableUploadProgressBar": true
}

We need to change a few things in order for the setup process to work.

First, make sure to set host to your VPS IP address, for example:

"host": "123.123.123.123",

If you need to use a port number other than the default 22, you can do so using the sshOptions field, for example:

"host": "123.123.123.123",
"sshOptions": { "port": 9876 },

Set the username value to whatever user you want to own your Meteor app’s installation. I recommend removing the password line and using an SSH key instead, for security purposes. Uncomment the line with the pem value and make sure it points to your SSH secret key that corresponds with the SSH public key you’ve installed on your VPS (in /root/.ssh/authorized_keys). Make sure to add a comma after the password line! If your SSH key has a passphrase attached to it, remove the pem line entirely, and make sure that your SSH private key is cached in an ssh agent (e.g. on Mac, ssh-add <path to ssh private key>).

Leave setupMongo set to its default value.

Change appName to the name of your Meteor app. In our case:

"appName": "myApp",

… and set the location of the app as well, relative to this deployment folder:

"app": "..",

Lastly, set the ROOT_URL to the designated URL for your app. Explicitly set a port number to the standard HTTP port.

// Configure environment
"env": {
  "ROOT_URL": "http://myapp.com",
  "PORT": 80
},

That’s it! Save the mup.json file, then run:

$ mupx setup

At this point mupx will ssh into your VPS, install Docker, set the environment up, and pull the appropriate Docker images. Now deploy your app:

$ mupx deploy

Now if you go to http://123.123.123.123, your app will show when the page loads.

Multi-core support

If your VPS has multiple cores, your Meteor app can take advantage of that. We’ll just have to make a couple quick tweaks.

First, you’ll need to install the cluster package. Go into the folder of your Meteor app (in this example, /projects/myApp), and type:

$ meteor add meteorhacks:cluster

Now edit your mup.json file and modify the environment variable section like so:

// Configure environment
"env": {
  "ROOT_URL": "http://myapp.com",
  "PORT": 80,
  "CLUSTER_WORKERS_COUNT": "auto"
},

Since we’ve added a new package to your app, you’ll have to redeploy.

$ mupx setup && mupx deploy

If you ever want to change your environment variables in mup.json without having to deploy the whole app, simply use the reconfigure command. This is useful when there were no application changes made.

$ mupx reconfig

Congratulations, your Meteor app is now up and running! Also, your app will automatically start whenever your VPS reboots. Keep an eye out for future articles on Meteor deployment and management.