How To Deploy a Meteor.js Application on Ubuntu 14.04 with Nginx

About Meteor.js

Meteor.js is a framework for JavaScript that allows web developers to write JavaScript code once and reuse it both client and server-side. This is possible thanks to Meteor’s unique build process (read more about structuring your application code and code sharing). This also solves the problem of needing a complicated deployment process between development mode, where developers code and debug, and production mode, that is secure enough for the public-facing version of the app. The Meteor framework provides a way for client-code and server-code as well as development and production to be closely related. It’s probably the easiest way for client-side developers to start working on server-side code!

To see this in action, you may want to view the introductory video on Meteor’s website.

Meteor.js allows you to develop projects like a website (web application), HTML5-based web-browser application (using AppCache), or mobile application (through integration with PhoneGap). All you need is knowledge of Javascript and HTML. Meteor includes support for MongoDB (a NoSQL database). Atmosphere hosts packages that can provide complete building blocks for your application to speed up the development even more.

At the end of this tutorial, we will have:

• Installed Meteor.js
• Created a deployment package that contains an entire Meteor application in a production-ready format (minus a web server and database backend)
• Installed Nginx as our web server to pass HTTP requests to Meteor
• Installed MongoDB as our database engine
• Managed our application with Upstart
• Configured daily database backups for the Meteor database

Throughout this tutorial, if you don’t have your own Meteor application yet, you can use the “Todo List” example application from the Meteor website.

Before You Begin

You should have:

• An existing Meteor app on a separate development computer (you can view the example “Todo List” app here; instructions are provided later in the tutorial)

• A fresh Ubuntu 14.04 server; existing Meteor installations should work in most cases

• root access to the server to execute commands

• Updated package lists. Execute:

   apt-get update
  

• Replace todos.net with the domain name you are actually using (or leave it if you don’t have a domain and will be using an IP address instead)

• Replace todos (without .net) with the name of your application

Step 1 — Setting Up an Nginx Web Server

We will install and set up Nginx because it allows us to encrypt web traffic with SSL, a feature that Meteor’s built-in web server does not provide. Nginx will also let us serve other websites on the same server, and filter and log traffic.

In our configuration, we will secure our site with an SSL certificate and redirect all traffic from HTTP to HTTPS. We will also utilize a few new security practices to enhance the security of the SSL connection.

In order to install Nginx we execute:

apt-get install nginx

Create a virtual host configuration file in /etc/nginx/sites-available.

Below is an annotated config file which we can create as /etc/nginx/sites-available/todos with the following contents. Explanations for all of the configuration settings are included in the comments in the file:

server_tokens off; # for security-by-obscurity: stop displaying nginx version

# this section is needed to proxy web-socket connections
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# HTTP
server {
    listen 80 default_server; # if this is not a default server, remove "default_server"
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html; # root is irrelevant
    index index.html index.htm; # this is also irrelevant

    server_name todos.net; # the domain on which we want to host the application. Since we set "default_server" previously, nginx will answer all hosts anyway.

    # redirect non-SSL to SSL
    location / {
        rewrite     ^ https://$server_name$request_uri? permanent;
    }
}

# HTTPS server
server {
    listen 443 ssl spdy; # we enable SPDY here
    server_name todos.net; # this domain must match Common Name (CN) in the SSL certificate

    root html; # irrelevant
    index index.html; # irrelevant

    ssl_certificate /etc/nginx/ssl/todos.pem; # full path to SSL certificate and CA certificate concatenated together
    ssl_certificate_key /etc/nginx/ssl/todos.key; # full path to SSL key

    # performance enhancement for SSL
    ssl_stapling on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 5m;

    # safety enhancement to SSL: make sure we actually use a safe cipher
    ssl_prefer_server_ciphers on;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:ECDHE-RSA-RC4-SHA:ECDHE-ECDSA-RC4-SHA:RC4-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK';

    # config to enable HSTS(HTTP Strict Transport Security) https://developer.mozilla.org/en-US/docs/Security/HTTP_Strict_Transport_Security
    # to avoid ssl stripping https://en.wikipedia.org/wiki/SSL_stripping#SSL_stripping
    add_header Strict-Transport-Security "max-age=31536000;";

    # If your application is not compatible with IE <= 10, this will redirect visitors to a page advising a browser update
    # This works because IE 11 does not present itself as MSIE anymore
    if ($http_user_agent ~ "MSIE" ) {
        return 303 https://browser-update.org/update.html;
    }

    # pass all requests to Meteor
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade; # allow websockets
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-Forwarded-For $remote_addr; # preserve client IP

        # this setting allows the browser to cache the application in a way compatible with Meteor
        # on every applicaiton update the name of CSS and JS file is different, so they can be cache infinitely (here: 30 days)
        # the root path (/) MUST NOT be cached
        if ($uri != '/') {
            expires 30d;
        }
    }
}

If you’d like to adapt the configuration file to your needs, and for more explanation, have a look at this tutorial on Nginx virtual hosts.

As seen in the virtual host config file, Nginx will expect a valid SSL certificate and key in /etc/nginx/ssl. We need to create this directory and secure it:

mkdir /etc/nginx/ssl
chmod 0700 /etc/nginx/ssl

Then we can create the files containing the certificate (and chain certificate if required) and the key in the locations we defined in the configuration above:

• certificate: /etc/nginx/ssl/todos.pem
• key: /etc/nginx/ssl/todos.key

If you do not have an SSL certificate and key already, you should now create a self-signed certificate using this tutorial on creating self-signed SSL certificates for Nginx. Remember that you’ll want to use the same names from the configuration file, like todos.key as the key name, and todos.pem as the certificate name. While a self-signed certificate is fine for testing, it is recommended to use a commercial, signed certificate for production use. A self-signed certificate will provoke Nginx warnings connected to ssl_stapling, and a security warning in the web browser.

When you’re done creating or obtaining your certificate, make sure you have the todos.pem and todos.key files mentioned above.

Next, we should disable the default vhost:

rm /etc/nginx/sites-enabled/default

And enable our Meteor vhost:

ln -s /etc/nginx/sites-available/todos /etc/nginx/sites-enabled/todos

Test that the vhost configuration is error free (you will see an error related to ssl_stapling if you have a self-signed certificate; this is okay):

nginx -t

If everything is looking good we can apply the changes to Nginx:

nginx -s reload

At this point, you can use your web browser to visit https://todos.net (or your IP address). It will show us 502 Bad Gateway. That is OK, because we don’t have Meteor running yet!

Step Two — Setting Up a MongoDB Database

We will install MongoDB from the regular Ubuntu repository. The standard configuration should be fine. There is no authentication required to connect to the database, but connections are only possible from localhost. This means that no external connections are possible, and thus the database is safe, as long as we don’t have untrusted users with SSH access to the system.

Install the MongoDB server package:

apt-get install mongodb-server

This is everything we need to do to get MongoDB running. To be sure that access from external hosts is not possible, we execute the following to be sure that MongoDB is bound to 127.0.0.1. Check with this command:

netstat -ln | grep -E '27017|28017'

Expected output:

tcp        0      0 127.0.0.1:27017         0.0.0.0:*               LISTEN
tcp        0      0 127.0.0.1:28017         0.0.0.0:*               LISTEN
unix  2      [ ACC ]     STREAM     LISTENING     6091441  /tmp/mongodb-27017.sock

In order to have daily backups available in case something goes wrong, we can optionally install a simple command as a daily cron job. Create a file /etc/cron.d/mongodb-backup:

@daily root mkdir -p /var/backups/mongodb; mongodump --db todos --out /var/backups/mongodb/$(date +'\%Y-\%m-\%d')

Step 3 — Installing the Meteor Application

First, we need to install Node.js. Since Meteor typically requires a version of Node.js newer than what’s available in the standard repository, we will use a custom PPA (at the time of writing, Ubuntu 14.04 provides nodejs=0.10.25~dfsg2-2ubuntu1 while Meteor 0.8.3 requires Node.js 0.10.29 or newer).

Execute the following to add a PPA with Node.js, and confirm by pressing Enter:

add-apt-repository ppa:chris-lea/node.js

Output:

 Evented I/O for V8 javascript. Node's goal is to provide an easy way to build scalable network programs
 More info: https://launchpad.net/~chris-lea/+archive/ubuntu/node.js
Press [ENTER] to continue or ctrl-c to cancel adding it

gpg: keyring `/tmp/tmphsbizg3u/secring.gpg' created
gpg: keyring `/tmp/tmphsbizg3u/pubring.gpg' created
gpg: requesting key C7917B12 from hkp server keyserver.ubuntu.com
gpg: /tmp/tmphsbizg3u/trustdb.gpg: trustdb created
gpg: key C7917B12: public key "Launchpad chrislea" imported
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)
OK

Now we must refresh the repository cache, and then we can install Node.js and npm (Node.js package manager):

apt-get update
apt-get install nodejs

It’s a good practice to run our Meteor application as a regular user. Therefore, we will create a new system user specifically for that purpose:

adduser --disabled-login todos

Output:

Adding user `todos' ...
Adding new group `todos' (1001) ...
Adding new user `todos' (1001) with group `todos' ...
Creating home directory `/home/todos' ...
Copying files from `/etc/skel' ...
Changing the user information for todos
Enter the new value, or press ENTER for the default
        Full Name []: 
        Room Number []: 
        Work Phone []: 
        Home Phone []: 
        Other []: 
Is the information correct? [Y/n]

Step Four — Configuring Upstart

Now we are ready to create the Upstart service to manage our Meteor app. Upstart will automatically start the app on boot and restart Meteor in case it dies. You can read more about creating Upstart service files in this tutorial.

Create the file /etc/init/todos.conf. Once again, it is annotated in-line:

# upstart service file at /etc/init/todos.conf
description "Meteor.js (NodeJS) application"
author "Daniel Speichert <daniel@speichert.pro>"

# When to start the service
start on started mongodb and runlevel [2345]

# When to stop the service
stop on shutdown

# Automatically restart process if crashed
respawn
respawn limit 10 5

# we don't use buil-in log because we use a script below
# console log

# drop root proviliges and switch to mymetorapp user
setuid todos
setgid todos

script
    export PATH=/opt/local/bin:/opt/local/sbin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    export NODE_PATH=/usr/lib/nodejs:/usr/lib/node_modules:/usr/share/javascript
    # set to home directory of the user Meteor will be running as
    export PWD=/home/todos
    export HOME=/home/todos
    # leave as 127.0.0.1 for security
    export BIND_IP=127.0.0.1
    # the port nginx is proxying requests to
    export PORT=8080
    # this allows Meteor to figure out correct IP address of visitors
    export HTTP_FORWARDED_COUNT=1
    # MongoDB connection string using todos as database name
    export MONGO_URL=mongodb://localhost:27017/todos
    # The domain name as configured previously as server_name in nginx
    export ROOT_URL=https://todos.net
    # optional JSON config - the contents of file specified by passing "--settings" parameter to meteor command in development mode
    export METEOR_SETTINGS='{ "somesetting": "someval", "public": { "othersetting": "anothervalue" } }'
    # this is optional: http://docs.meteor.com/#email
    # commented out will default to no email being sent
    # you must register with MailGun to have a username and password there
    # export MAIL_URL=smtp://postmaster@mymetorapp.net:password123@smtp.mailgun.org
    # alternatively install "apt-get install default-mta" and uncomment:
    # export MAIL_URL=smtp://localhost
    exec node /home/todos/bundle/main.js >> /home/todos/todos.log
end script

One thing to notice in this configuration file is the METEOR_SETTINGS parameter. If you use meteor --settings config.json when launching Meteor’s development mode, then you should paste the contents of config.json as a variable in METEOR_SETTINGS.

The MAIL_URL must be a valid SMTP URL only if you plan to use Meteor’s Email package. You can use MailGun (as recommended by Meteor), a local mail server, etc.

As we can see in the file, the log will be saved to /home/todos/todos.log. This file will not rotate and WILL GROW over time. It’s a good idea to keep an eye on it. Ideally, there should not be a lot of content (errors) in it. Optionally, you can set up log rotation or replace >> with > at the end of Upstart scripts in order to overwrite the whole file instead of appending to the end of it.

Don’t start this service yet as we don’t have the actual Meteor application files in place yet!

Step Five — Deploying the Meteor Application

Optional: If you do not have a Meteor project yet

If you don’t have a Meteor project yet and would like to use a demo app, that’s not a problem!

Do this next step on your home computer or a development Linux server. Commands may vary based on your OS. Move to your home folder:

cd ~

First, install Meteor’s development version:

curl https://install.meteor.com | /bin/sh

Then create an application from an example, called Todo List:

meteor create --example todos

Now enter the directory of your application and you are ready to continue:

cd todos

All Meteor projects

It’s time to create a production-version bundle from our Meteor app. The following commands should be executed on your home computer or development Linux server, wherever your Meteor application lives. Go to your project directory:

cd /app/dir

And execute:

meteor build .

This will create an archive file like todos.tar.gz in the directory /app/dir. Copy this file to your ~ directory on your Droplet.

scp todos.tar.gz root@todos.net:~

Now go back to your Droplet. Create a project directory and move the archive project file into it. Note that this is the home folder for the project user that we created previously, not your root home folder:

mkdir /home/todos
mv todos.tar.gz /home/todos

Move into the project directory and unpack it:

cd /home/todos
tar -zxf todos.tar.gz

Take a look at the project README:

cat /home/todos/bundle/README

The bundle includes a README file with contents:

This is a Meteor application bundle. It has only one external dependency:
Node.js 0.10.29 or newer. To run the application:

  $ (cd programs/server && npm install)
  $ export MONGO_URL='mongodb://user:password@host:port/databasename'
  $ export ROOT_URL='http://example.com'
  $ export MAIL_URL='smtp://user:password@mailhost:port/'
  $ node main.js

Use the PORT environment variable to set the port where the
application will listen. The default is 80, but that will require
root on most systems.

Find out more about Meteor at meteor.com.

This recipe is reflected in our /etc/init/todos.conf file. There is still one more thing mentioned in the README that we need to do.

Now we need to install some required npm modules. To be able to build some of them, we also need to install g++ and make:

apt-get install g++ make
cd /home/todos/bundle/programs/server
npm install

You should see output like this:

npm WARN package.json meteor-dev-bundle@0.0.0 No description
npm WARN package.json meteor-dev-bundle@0.0.0 No repository field.
npm WARN package.json meteor-dev-bundle@0.0.0 No README data
 
> fibers@1.0.1 install /home/todos/bundle/programs/server/node_modules/fibers
> node ./build.js

`linux-x64-v8-3.14` exists; testing
Binary is fine; exiting
underscore@1.5.2 node_modules/underscore

semver@2.2.1 node_modules/semver

source-map-support@0.2.5 node_modules/source-map-support
└── source-map@0.1.29 (amdefine@0.1.0)

fibers@1.0.1 node_modules/fibers

The reason we need to do this is because our application bundle does not contain modules and libraries that are platform-dependent.

We are almost ready to run the application, but since we operated on files as root, and they should be owned by the todos user, we need to update the ownership of the project directory:

chown todos:todos /home/todos -R

Step Six — Showtime

At this point we have everything we need to run our Meteor application:

• Node.js environment installed
• Application installed in its project directory
• Upstart service configured to run the application
• MongoDB database
• Nginx proxy server in front of our Meteor application to provide SSL encryption

To start our application, let’s execute this command from the project directory:

start todos

Now you should be able to view your application in the browser at https://todos.net.

Re-deploying the Application

When you make changes in the development mode (and you will; we are developers after all!), you can simply repeat Step Five (starting from meteor build) and go through most of the steps until the restart todos command, which will reload your application via Upstart.

This way you can push a new version with no downtime. Clients (visitors to your website) will automatically pull the new version of code and refresh their page - that is Meteor’s magic!

If you want to test this, you can make a simple change to the text in the todos/client/todos.html page in your development copy of the app on your home computer or development server.

Development server:

Build:

meteor build /app/dir

Upload:

scp todos.tar.gz root@todos.net:/home/todos

Production server:

Expand:

tar -zxf /home/todos/todos.tar.gz

Move into the project folder:

cd /home/todos/bundle/programs/server

Update the npm modules (you may see a few warnings):

npm install

Restart the app:

restart todos

Troubleshooting

If something goes wrong, here are a few hints on where to look for problems:

• Check /home/todos/todos.log if your application starts and dies; it should throw an appropriate error message (e.g. in case of a programming error).
• Check /var/log/nginx/error.log if you see an HTTP error in stead of your application.
• Check /var/log/mongodb/mongodb.log if you think there might a problem with the database.

Finally, check if all services are running:

status todos
service nginx status
status mongodb

/home/****/bundle/programs/server/node_modules/fibers/future.js:173
            throw(ex);
                  ^
Error: /home/****/bundle/programs/server/npm/npm-bcrypt/node_modules/bcrypt/build/Release/bcrypt_lib.node: invalid ELF header
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.require (module.js:364:17)
    at require (module.js:380:17)
    at bindings (/home/****/bundle/programs/server/npm/npm-bcrypt/node_modules/bcrypt/node_modules/bindings/bindings.js:74:15)
    at Object.<anonymous> (/home/****/bundle/programs/server/npm/npm-bcrypt/node_modules/bcrypt/bcrypt.js:1:97)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)

2014/10/07 23:45:03 [error] 3266#0: *135 connect() failed (111: Connection refused) while connecting to upstream, client: 208.123.162.2, server: mysite.com, request: "GET /favicon.ico HTTP/1.1", upstream: "http://127.0.0.1:8080/favicon.ico", host: "mysite.com"

# HTTP
server {
    listen 80 default_server; # if this is not a default server, remove "default_server"
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html; # root is irrelevant
    index index.html index.htm; # this is also irrelevant

    server_name mysite.com; # the domain on which we want to host the application. Since we set "default_server" previously, nginx will answer all hosts anyway.

    # If your application is not compatible with IE <= 10, this will redirect visitors to a page advising a browser update
    # This works because IE 11 does not present itself as MSIE anymore
    if ($http_user_agent ~ "MSIE" ) {
        return 303 https://browser-update.org/update.html;
    }

    # pass all requests to Meteor
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade; # allow websockets
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-Forwarded-For $remote_addr; # preserve client IP

        # this setting allows the browser to cache the application in a way compatible with Meteor
        # on every applicaiton update the name of CSS and JS file is different, so they can be cache infinitely (here: 30 days)
        # the root path (/) MUST NOT be cached
        if ($uri != '/') {
            expires 30d;
        }
    }
}

listen 80;
# listen 80 default_server; # if this is not a default server, remove "default_server"
# listen [::]:80 default_server ipv6only=on;