How To Run A Meteor App Securely With Sandstorm on Ubuntu 14.04

Written in collaboration with Sandstorm

Introduction

Meteor is a framework for JavaScript that allows web developers to write JavaScript code once and reuse it both client- and server-side. Another tutorial describes how to deploy Meteor apps using Nginx and Upstart, but this tutorial covers a different approach for deploying Meteor apps: creating and running a Sandstorm package.

Sandstorm is an open source platform for personal servers, which means that it can be used to install many different apps on one server with a very easy to use interface. A prevoius tutorial showed how to install Sandstorm to run apps like WordPress and MediaWiki; this tutorial covers how to run a custom application, like one you’ve written yourself.

In Sandstorm, installing an app enables you to create new documents using that app. Each document is a separate running instance of the app, and the code powering each document (which Sandstorm calls a grain) is private by default. This is the sense in which Sandstorm makes it easy to run Meteor apps securely; Sandstorm handles access control. In this tutorial, you’ll see how to install the app and then create multiple app instances.

There are multiple use cases for wanting to create a Sandstorm app. The first use case is for personal or corporate use. This would mean packaging an app and deploying it on your or your company’s Sandstorm server and make use of Sandstorm’s sandboxing and access control. Another use case is the creation of a Sandstorm app to publish it for other Sandstorm user’s. This could for example be published on apps.sandstorm.io, but you could also distribute it yourself. The user will know that the apps’ developer cannot read their data. This tutorial applies to both scenarios.

Prerequisites

To follow this tutorial, you will need:

• A local computer, which will be used to build the Sandstorm package. This computer needs to:

  • Be a 64-bit machine with at least 1GB of RAM. This tutorial has instructions for Ubuntu 14.04 and Mac OS X.

  • Have Git installed, which will be used to download vagrant-spk and our example application. You can install Git by following this Git tutorial for Ubuntu 14.04, or the Git Mac installation guide for OS X.

  • Have Vagrant installed, which you can do from Vagrant’s installation page. Vagrant is used to create a virtual machine in which Sandstorm runs in development mode.

  • Have some virtualization software, like VirtualBox, installed.

• One Ubuntu 14.04 Droplet with Sandstorm installed to test your package, which you can do by following this previous tutorial.

• Optionally, an app that you want to package, written using the Meteor framework. This tutorial shows the steps using a sample to-do list application provided by Meteor if you don’t have another app you want to use.

Step 1 — Downloading the Example App and vagrant-spk

In this step, we will download the Meteor application we will be creating a Sandstorm package for, and also Sandstorm’s packaging tool, vagrant-spk.

First, create and move into a new directory called projects, to avoid your home directory from getting cluttered with new files.

mkdir ~/projects
cd ~/projects

The sample application we will be using in this tutorial is simple-todos, an application provided by Meteor. However, you can also skip this if you want to use your own Meteor application.

Download this application by cloning it from Meteor’s GitHub.

git clone https://github.com/meteor/simple-todos.git

Next, we’ll install vagrant-spk (which is Sandstorm’s packaging tool) from Sandstorm’s GitHub.

git clone git://github.com/sandstorm-io/vagrant-spk

Move into the vagrant-spk directory.

cd vagrant-spk

Finally, create a symbolic link to the binary in /usr/local/bin to make the vagrant-spk command available.

sudo ln -s $PWD/vagrant-spk /usr/local/bin

After installing, you can check if vagrant-spk is installed by running:

vagrant-spk --help

You should see a message like:

Output
usage: vagrant-spk [-h]
                       [--work-directory WORK_DIRECTORY]
                       {destroy,dev,global-status,halt,init,pack,publish,setupvm,ssh,up}
                       [command_specific_args [command_specific_args ...]]
. . .

Step 2 — Running the Sandstorm VM

In this section, we will create the actual Sandstorm package. Start by moving into the application directory on your local machine.

cd ~/projects/simple-todos

Then, set up the virtual machine that will be using to build the package.

vagrant-spk setupvm meteor

You’ll see output similar to this:

Output
Initializing .sandstorm directory in /home/sammy/projects/simple-todos/.sandstorm
Creating /home/sammy/.sandstorm to hold developer keys.
Creating /home/sammy/.sandstorm/caches to hold sandstorm installer caches.

Next, start the virtual machine.

vagrant-spk up

This command will take a moment to execute.

Step 3 — Creating the Package Definition

In this section, we will actually package the Meteor application.

First, create the package definition which Sandstorm will use.

vagrant-spk init

This command will create a file called sandstorm-pkdef.capnp in the directory .sandstorm. We will need to make some changes to this file.

Connect to the Vagrant VM.

vagrant-spk ssh

Then open /opt/app/.sandstorm/sandstorm-pkdef.capnp using nano or your favorite text editor.

nano /opt/app/.sandstorm/sandstorm-pkgdef.capnp

Find the following section:

Original ~/.sandstorm/sandstorm-pkgdef.capnp
. . .
    # This manifest is included in your app package to tell Sandstorm
    # about your app.

    appTitle = (defaultText = "Example App"),

    appVersion = 0,  # Increment this for every release.
. . .

Change the value in the appTitle line to “Todo”.

Modified ~/.sandstorm/sandstorm-pkgdef.capnp
. . .
    # This manifest is included in your app package to tell Sandstorm
    # about your app.

    appTitle = (defaultText = "Todo"),

    appVersion = 0,  # Increment this for every release.
. . .

Then save and close the file.

Step 4 — Adding Sandstorm Login to the App

Right now, the Todos app has separate authentication from Sandstorm. However, we want to be logged in with the Todos application when we are logged in to Sandstorm, so we will need to add a separate package to the Meteor app.

While still connected to the VM, change to to the main package directory.

cd /opt/app

Next, we will add the kenton:accounts-sandstorm package to the Meteor app, which exposes the current Sandstorm account to the Meteor app.

meteor add kenton:accounts-sandstorm

You can now exit the connection with the Vagrant VM.

exit

In the case of this Todo application, the page still contains login and logout buttons, which are not necessary. Next, we’ll remove them.

Open the file simple-todos.html in the project/simple-todos directory using your favorite text editor.

nano simple-todos.html

Find the following section and remove the loginButtons line, highlighted in red below. Then save and close the file.

simple-todos.html
. . .
        Hide Completed Tasks
      </label>

      {{> loginButtons}}

      {{#if currentUser}}
. . .

Next, open the file simple-todos.js.

nano simple-todos.js

Like before, delete the following lines highlighted in red, then save and close the file. Make sure not to delete the final curly brace.

simple-todos.js
. . .
    "click .toggle-private": function () {
      Meteor.call("setPrivate", this._id, ! this.private);
    }
  });

  Accounts.ui.config({
    passwordSignupFields: "USERNAME_ONLY"
  });
}
. . .

Now the app uses Sandstorm accounts instead of Meteor accounts.

Step 5 — Testing the App in Development

vagrant-spk has a dev command which makes the Sandstorm VM run in development mode, making your package available. So, run the command from your app’s directory (in this case simple-todos).

vagrant-spk dev

When it has finished initializing, it will print the following message:

Output
App is now available from Sandstorm server. Ctrl+C to disconnect.

This means you can now visit Sandstorm at http://local.sandstorm.io:6080/. You can now log in by pressing on with a Dev Account.

Then click Alice (admin). This will log you in with an admin account, which will allow you to create new instances. You can leave the default values for the Confirm your profile page, and press the purple Continue button without changing anything.

Next, click on the Todo app, then click Create new instance.

Step 6 — Creating and Uploading an SPK

The final step in creating a Sandstorm package is to create an SPK file containing the app, a copy of Meteor, and any further dependencies for the app. This step is fully automated by the meteor-spk tool.

First, stop your development server by pressing CTRL+C. Then, package the app.

vagrant-spk pack todo.spk

This creates a SPK file in your current directory.

As an aside, in our case, the SPK file is about 11 MB. Sandstorm apps are typically a handful of megabytes even though they contain the app and all the dependencies, including any operating system dependencies.

When you have finished developing an app, you need to shut down the virtual machine before creating a second app. Therefore, execute the following command:

vagrant-spk halt

If you want to continue the development for whatever reason, you can simply run vagrant-spk up.

Step 7 — Creating a Todo List

In this section, we will install the package on the Sandstorm server on your Droplet and create a new instance of the app.

Log into your Sandstorm on your Droplet and you will see an Upload app button in your home screen. Click that button, and choose the SPK file via your web browser that you have created in step 6.

This will create a new item in your Sandstorm home screen labeled Todo. Installing an app in Sandstorm gives you the ability to create new instances (or documents). Therefore, click the item Todo. This will take you to the following screen:

Click on Create new instance. This will take you into a new Todo instance, powered by a unique instance of the Todo list app.

Each instance is called a grain in Sandstorm. This app instance is unique to your Sandstorm user. If you try to open the URL in a private browsing window in your web browser, you will get a Forbidden error. You can use the blue Share button in the Sandstorm top bar to create a sharing link, if you want others to have access to the Todo list.

You can leave this todo list by clicking on the Sandstorm logo in the top-left. Once you’ve done that, you’ll see you can create another Todo list. Any data you input into one Todo list instance is totally independent of the other ones.

Conclusion

We have seen how to take a codebase written in Meteor and package it for Sandstorm. It relies on Sandstorm for access control and can easily be shared with others. To learn more about Meteor, visit their website. To learn more about Sandstorm, visit sandstorm.io.