Sandstorm packaging guide

Style: Hands-on introductory tutorial.

This tutorial will show you how to package an app for Sandstorm in five minutes. Going through this tutorial, you’ll learn:

How to take an existing web application and turn into a Sandstorm package (SPK). We’ll use a PHP example; Sandstorm supports any app that runs on Linux, such as Meteor, Python, Node, PHP, C++, and more.
How our packaging helper (vagrant-spk) lets you edit the app’s files on your main operating system (Mac or Linux; working on Windows support), even though Sandstorm apps always run on Linux.

Once you’ve worked through this tutorial, look in the Next steps section at the bottom of this document to learn more about how to improve the speed of packaging on your computer, learn about user authentication and permissions in Sandstorm, and more.

Overview of Sandstorm packages

A Sandstorm application package includes all the code needed to run your app, including all binaries, libraries, modules, etc. Normally, figuring out exactly what to put in a package could be tedious, and if you decide to include everything, it would result in a massive package file. Sandstorm makes it easy to keep things small by employing a trick: it watches your server running on your development machine and pulls in all the files the server uses.

Keeping the package small means that it’s easy for people to install and update the package you’re creating.

Sandstorm packages rely on the Sandstorm platform to handle adding new user accounts and other access control elements. Read more in the App Developer Handbook.

Let’s walk through an example.

Prerequisites

Learn about Sandstorm, if you haven’t already. Try using Sandstorm at our demo server to get a feel for how it operates.
Open a “terminal” on your Mac or Linux system.
Don’t use sudo unless we tell you to!

Ensure git is installed

In this tutorial, we use git to download some code, so you need it on your computer.

In the terminal, type the following and press enter.

git --version

You should see a message like:

git version x.y.z

If so, git is properly installed and you can skip this section.

If you saw instead a message like:

git: Command not found.

Then you need to install git via the following instructions.

On Mac OS, visit the official git for Mac download page and follow their instructions.
On Ubuntu or Debian, run: sudo apt-get install git. (On other Linux systems, use your package manager to install git.)

Ensure Vagrant is installed

In this tutorial, we use Vagrant (along with other tools) to create a Linux virtual machine where your app will run, alongside Sandstorm.

To check if it is installed, in the terminal, type the following and press enter.

vagrant version

You should see a message like:

Installed Version: 1.7.2

If so, Vagrant is installed properly, and you can skip the rest of this section.

If instead you see a message like:

vagrant: Command not found.

Then you need to install Vagrant by doing the following.

On Mac OS or Linux, visit the official Vagrant website and follow their instructions to install it.

Ensure VirtualBox is installed

In this tutorial, we use VirtualBox to emulate a computer on which we run Linux, controlled via Vagrant.

To check if it is installed, in the terminal, type the following and press enter:

VirtualBox --help

You should see a lot of output, for example:

Oracle VM VirtualBox Manager x.y.z

If so, skip the rest of this section, as VirtualBox is already properly installed.

If you saw instead:

VirtualBox: Command not found.

Then you need to install VirtualBox by doing following:

Visit the VirtualBox downloads page
In the top, underneath VirtualBox platform packages, find the package for your operating system. Click the link, download, and install it.
Once you are done with that, go to the top of this section and make sure you can see the VirtualBox help output.

Make sure you have git installed

Note that you do not need Sandstorm installed on your computer before you start packaging an app. Sandstorm’s vagrant-spk helper tool handles installing it for you to test the app in.

Install `vagrant-spk`

The first Sandstorm-specific step is to install Sandstorm’s main packaging helper called vagrant-spk. This tool uses Vagrant and VirtualBox so that you can run your app within Sandstorm on a Linux virtual machine.

In your terminal, run the following commands to download and install vagrant-spk.

mkdir -p ~/projects

cd ~/projects

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

cd vagrant-spk

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

(Note: If you prefer different paths, that is OK.)

Creating a package

Over the course of section, we will use vagrant-spk to create a Sandstorm package containing the app and all its dependencies.

Choose an app that you will package

This tutorial uses a sample PHP web app. To download it, run the following commands:

cd ~/projects

git clone git://github.com/paulproteus/php-app-to-package-for-sandstorm

The app’s code will be stored at ~/projects/php-app-to-package-for-sandstorm. We will spend the rest of the tutorial in that directory.

Note: Feel free to spend a moment looking around this folder you just downloaded. You’ll find an index.php, and some CSS and Javascript.

Create .sandstorm, to store packaging information for the app

Over the course of this tutorial, we will create and modify the .sandstorm/ directory in the project. This directory contains the Sandstorm packaging information, such as the app name and the scripts required to create the package.

We’ll use the vagrant-spk tool to create this directory.

The purpose of vagrant-spk is to create a Linux system where Sandstorm and your app run successfully. It acts differently based on which language platform you want to use. In our case, we’ll use the lemp platform: Linux, nginx, MySQL, and PHP.

To do that, run the following commands:

cd ~/projects/php-app-to-package-for-sandstorm

vagrant-spk setupvm lemp

You should see a message like the following:

Initializing .sandstorm directory in /Users/myself/projects/php-app-to-package-for-sandstorm/.sandstorm

You should also find that the .sandstorm/ directory now exists in your project. Here’s how you can take a look:

ls ~/projects/php-app-to-package-for-sandstorm/.sandstorm

You should see a collection of files there.

Start a virtual Linux machine containing Sandstorm

The next step is to start the virtual Linux machine, containing Sandstorm, that you will develop the package with. To do that, run the following command:

vagrant-spk up

You will see a lot of messages printed out. Some of them are not necessary; we’re working on tidying up the scripts to minimize the noise.

Eventually, you will see this mesage:

==> default: Processing triggers for php5-fpm (5.6.9+dfsg-0+deb8u1) ...

and get your shell back. At this point, you can continue to the next step.

Troubleshooting note: If you already have Sandstorm installed on your laptop, you might see the following red text:

Vagrant cannot forward the specified ports on this VM, since they would collide with some other application that is already listening on these ports. The forwarded port to 6080 is already in use on the host machine.

If you see that, run:

sudo service sandstorm stop

and halt any other vagrant-spk virtual machines you might be using to develop other apps.

Examine the Sandstorm instance you will develop against

Your system is now running a Sanstorm instance. You should visit it in your web browser now by visiting

http://local.sandstorm.io:6080/

Take a moment now to sign in by clicking on Sign in in the top-right corner. Choose Sign in with a Dev account and choose Alice (admin) as the user to sign in with.

Note that there are other “dev accounts” available – you can use this to test the experience of using your app as other users.

Over the next few steps, we will prepare the app so that it is visible in that Sandstorm instance.

(Editor’s note: We should make localhost:6080 work, so that people don’t have to learn about local.sandstorm.io.)

Use vagrant-spk to create a package definition file for your app

Every Sandstorm package needs to declare its name. It does this in a sandstorm-pkgdef.capnp file. (capnp is short for Cap’n Proto; for the purpose of this tutorial, Cap’n Proto is a configuration file format that is easy for Sandstorm to parse.)

Let’s use vagrant-spk to create a package definition file by running:

vagrant-spk init

This will create a new file called .sandstorm/sandstorm-pkdef.capnp.

We’ll make two changes. First, we’ll give our app a title of Sandstorm Showcase. To do that, open .sandstorm/sandstorm-pkgdef.capnp in a text editor and find the line with this text:

appTitle = (defaultText = "Example App"),

Change it to the following.

appTitle = (defaultText = "Sandstorm Showcase"),

Second, we will customize the text that Sandstorm users see when they want to create a new instance of the app. To do this, find the line containing:

( title = (defaultText = "New Instance"),

and change it to read:

( title = (defaultText = "New Showcase"),

Make the app available in the Sandstorm, in development mode

Sandstorm app development focuses around dev mode, which makes the current code of an app available.

Make this app available in dev mode by doing:

vagrant-spk dev

On the terminal, you will see a message like:

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

Now you can visit the Sandstorm at http://local.sandstorm.io:6080/ and log in as Alice (admin). Your app name should appear in the list of apps.

You can click New Showcase and see the PHP code running.

Note that each app instance (each “Showcase”, for this app) runs separate from each other. You can see that for this app because the app stores the number of times you have reloaded the page. If you create another New Showcase, each instance will store their data separately.

In Sandstorm, resources like a database are embedded into the package. That helps enforce this isolation between app instances.

Stop the development server and create a package file

The final step in this tutorial is to create a Sandstorm package (SPK) file, containing the app and all its dependencies. This SPK file is something that you can give directly to people who want to use the code, or add to the Sandstorm app list so people can install it easily from their own servers.

To do that, we first stop the vagrant-spk dev server. To do that, type Ctrl-C on your keyboard. You will see some messages like:

Unmounted cleanly. Updating file list.

If you’re still logged into your Sandstorm instance, you will notice the app vanishing from the list of apps on the left.

To create the SPK file, run:

vagrant-spk pack ~/projects/package.spk

This will take a few moments, and once it is done, there will be a file in ~/projects/package.spk that contains the full app.

You can see how large it is by running the following command:

du -h ~/projects/package.spk

On my system, I see:

16M

or sixteen megabytes.

Now, you can upload this to your development Sandstorm instance by clicking *Upload app and choosing this file in your web browser’s upload dialog.

To learn how to go further and share this SPK file, or what you should know for other web frameworks, check out the What’s next section below.

(Editor’s note: IMHO vagrant-spk pack should auto-guess a reasonable package filename.)

What’s next

Now that you’ve seen the basics of how a Sandstorm app works, you might be interested in any of the following:

What makes a great Sandstorm app? See the App Developer Handbook.
How do I learn more about the technical underpinnings of vagrant-spk? Merge current README into this.
How do I package-up a Python, or Meteor app? Keep reading.
How do I make vagrant-spk faster? Drew can type this.
How should I manage my package signing keys?
Will this work on Windows? Will this work if I typically run Sandstorm-related programs in a virtual machine?

Information on how vagrant-spk handles other programming languages/frameworks

Meteor

For a Meteor app, keep the following in mind:

Get a copy of the app code wherever you like. Alternatively, run meteor create --example todos
cd into that directory.
Run vagrant-spk setupvm meteor
Run vagrant-spk up. Note this will print lots of red text; sorry about that, then abruptly end.
Run vagrant-spk init and edit .sandstorm/sandstorm-pkgdef.capnp
Run vagrant-spk dev and make sure the app works OK at http://local.sandstorm.io:6080/
Run vagrant-spk pack ~/projects/meteor-package.spk and you have a package file!

If you want to package a Meteor ap