NotAlexNoyle/Haboob
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add initial docs for Sandstorm + vagrant-spk

Browse Source 
The primary purpose of this commit is to store a vagrant-spk
packaging tutorial somewhere that people can find it. It also creates
a structure for future Sandstorm documentation, organized similarly
to the Django documentation.

If you have mkdocs installed, you can generate HTML based on this
by being in the Sandstorm directory and running:

mkdocs
This commit is contained in:
Asheesh Laroia committed 2015-06-17 19:11:32 -07:00
1 parent 462e025a56
commit 6b0ad27168
9 files changed
+823
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/index.md
+40
View File
@@ -0,0 +1,40 @@
# Sandstorm documentation
## What is Sandstorm? See [sandstorm.io](https://sandstorm.io)
Sandstorm is an open source platform for personal servers.
Sandstorm lets you run your own server and install apps like
EtherCalc, GitLab, Etherpad, LibreBoard, and more as easily as you'd
install apps on your phone.
### [Try the demo](https://demo.sandstorm.io)
## Caveats
### *WARNING! WARNING!*
Sandstorm is in the very early stages of development. We want developers to start playing with it, but please don't rely on it for mission-critical data or security yet.
## First steps
Are you new to Sandstorm, packaging Sandstorm apps, or running your
own server? This is the place to start.
* **Totally new:** [Overview](overview.md) | [Installing Sandstorm on a server](install.md)
* **Packaging tutorial:** [Learn how to package a web app for Sandstorm from Mac OS or Linux](vagrant-spk/packaging-tutorial.md)
* **Get involved:** [Learn how to make a positive difference in the Sandstorm community](https://github.com/sandstorm-io/sandstorm/wiki/Get-Involved)
## Reference documentation
We call Sandstorm a _platform_ because it provides concepts,
capabilities, and APIs that apps can use. To learn more about these,
read the [GitHub wiki](http://github.com/sandstorm-io/sandstorm/wiki).
## App packaging
If you learn the concepts and skills to take you beyond the
introductory packaging tutorial, check out the following:
* Sandstorm platform overview: See the [Sandstorm App Developer Handbook](https://github.com/sandstorm-io/sandstorm/wiki/Sandstorm-App-Developer-Handbook) for information on app isolation, granularity, writable `/var`, and more.
* vagrant-spk: [Overview](vagrant-spk/index.md) | [Installation](vagrant-spk/installation.md) | [Customizing & understanding vagrant-spk](vagrant-spk/customizing.md) | [Platform stacks for Meteor, Python, PHP, and DIY](vagrant-spk/platform-stacks.md)
docs/install.md
+112
View File
@@ -0,0 +1,112 @@
# Installation
We recommend **the easy way** if you are running your own server.
## Installing the Easy Way
*Prerequisite:* Linux x86_64, with kernel version 3.13 or later.
To install on your own Linux machine, see
[https://install.sandstorm.io/](https://install.sandstorm.io) or run:
```bash
curl https://install.sandstorm.io | bash
```
Note: If installing Sandstorm under LXC / Docker, you will need to choose the option to
install as a non-root user. Unfortunately, this means the development tools will not
work. This is due to the interaction between Sandstorm and Docker's use of Linux
containerization features and missing features in the Linux kernel which we
hope will be fixed eventually. For non-development purposes, Sandstorm should run just fine
under Docker.
### Tips
* If you want to run on port 80, we recommend setting up an [nginx](http://nginx.org/) reverse
proxy rather than trying to get Node to open port 80 directly. Make sure to configure
[WebSocket forwarding](http://nginx.org/en/docs/http/websocket.html), which requires nginx
1.3.13 or better.
* If you want SSL, then you will definitely need an nginx proxy (or something equivalent). You will
further need to use a wildcard certificate.
For reference,
[nginx-example.conf](https://github.com/sandstorm-io/sandstorm/tree/nginx-example.conf)
contains the http server part of nginx config used by Sandstorm Alpha.
## Installing from Source
### Prerequisites
Please install the following:
* Linux x86_64, with kernel version 3.13 or later
* C and C++ standard libraries and headers
* GNU Make
* `libcap` with headers
* `xz`
* `zip`
* `unzip`
* `strace`
* `curl`
* ImageMagick
* discount (markdown parser)
* [Clang compiler](http://clang.llvm.org/) version 3.4 or better
* [Meteor](http://meteor.com)
On Debian or Ubuntu, you should be able to get all these with:
sudo apt-get install build-essential libcap-dev xz-utils zip \
unzip imagemagick strace curl clang-3.4 discount
curl https://install.meteor.com/ | sh
### Building / installing the binaries
Build the Sandstorm bundle:
make
(Note: You should *not* use `-j`, as we only use make as a meta-build system. The major components will utilize all CPU cores.)
Install it:
make install
This installs your locally-built bundle just as would get if you had installed using
`https://install.sandstorm.io`. You will be asked various configuration questions. If you intend
to hack on Sandstorm itself, you should choose to run the server to run under your local user
account (the default is to create a separate user called `sandstorm`).
If Sandstorm is already installed, you can update to your newly-built version like so:
make update
Note that this only works if you installed Sandstorm to run at startup. Otherwise, you will
have to manually do:
/path/to/sandstorm update sandstorm-0.tar.xz
### Hacking on the shell
You can run the shell (front-end) in dev mode so that you can modify it without rebuilding the
whole bundle for every change. Just do:
cd shell
sudo service sandstorm stop-fe
./run-dev.sh
Now connect to your local server like you normally would.
Later, when you are done hacking, you may want to restart the installed front-end:
sudo service sandstorm start-fe
### Hacking on the C++
If you're going to edit C++, you will want to install [Ekam](https://github.com/sandstorm-io/ekam), the build system used by Sandstorm. Be sure to read Ekam's wiki to understand how it works.
Once `ekam` is in your path, you can use `make continuous` in order to start an Ekam continuous build of Sandstorm. While this build is running, you can also run other `make` commands in a separate window. This will automatically synchronize with your continuous build rather than starting a second build.
To do a debug build, run make like:
make continuous CXXFLAGS="-g"
If you suspect you'll be hacking on Sandstorm's dependencies as well, you may want to follow the dependency symlink trick described in the Ekam readme.
docs/overview.md
+13
View File
@@ -0,0 +1,13 @@
# How It Works
* Sandstorm's server-side sandboxing is based on the same underlying Linux kernel features as LXC and Docker. We use the system calls directly for finer-grained control.
* (Planned) The kernel attack surface is reduced using seccomp-bpf to block and/or virtualize system calls.
* procfs, sysfs, etc. are not mounted in the sandbox, and only a minimal set of devices are available.
* (Planned) On the client side, apps run in a sandboxed iframe employing the `Content-Security-Policy` header to prevent them from sending any kind of network communication to any server other than their own.
* All communication between the sandboxed server and the outside world takes place through a single [Cap'n Proto](http://capnproto.org) RPC socket which the app's root process receives as file descriptor #3. We've provided a program, `legacy-bridge`, which can receive HTTP-over-RPC requests on this socket and proxy them to a regular HTTP server running in the sandbox.
* Every object (e.g., each document) that you create with an application runs in a separate isolated sandbox. We sandbox per-object rather than per-app so that it is easy and safe to share one object without also sharing everything created using the same app.
* An application package (`.spk` file) is essentially an archive containing an entire chroot environment in which the application runs.
* The application runs with the contents of its package mounted read-only, so that multiple instances of the same app can share disk space for the package.
* The application may store persistent state in the `/var` directory.
* App servers are aggressively killed off as soon as the user closes the browser tab, then restarted when the user returns later.
* Packages are cryptographically signed. Packages signed with the same key represent versions of the same app, and are thus allowed to replace older versions -- although the user must still confirm these upgrades.
docs/vagrant-spk/customizing.md
+155
View File
@@ -0,0 +1,155 @@
# Customizing and understanding vagrant-spk
## What the files are for
`vagrant-spk` will create a `.sandstorm/` folder in your repo and set up some
files with some defaults for your app stack. You will likely need to modify
some of these to adapt their behavior to make the most sense for your app.
### global-setup.sh
This installs Sandstorm using the official installer script, enables developer
accounts, and stops unneeded services on the VM. It caches the Sandstorm
bundle to speed up subsequent runs. You should not need to change this script.
### setup.sh
This script runs when you set up the VM by `vagrant-spk up` the first time and
does stack-specific setup, like installing tools or daemons needed to build and
run your app. `vagrant-spk` provides some defaults based on commonly-used platform
stacks, but you'll likely want to modify this script as suitable for your package.
This is the ideal place to `apt-get install` system packages your app relies on,
like:
- language runtimes (PHP, Node, Python, etc.)
- database engines (MySQL, PostgreSQL, Redis, etc.)
- frontend web servers (nginx, Apache)
and so on. Please note that this script is run only once for the lifetime of
the VM, and will not be run again when running `vagrant-spk dev` or starting a
grain.
If you make changes to this script, you should destroy your VM (`vagrant-spk destroy`)
and rebuild it cleanly from scratch (`vagrant-spk up`) to make sure your
changes take effect and work as desired.
If you find yourself destroying and creating VMs from scratch frequently,
consider running an instance of `apt-cacher-ng` on your host to speed up
package downloads.
### build.sh
This script runs each time you run `vagrant-spk dev` before exposing your app
to the Sandstorm server, so you can run it in "dev mode". Again, `vagrant-spk`
provides some defaults based on commonly-used patterns in the supported stacks,
but you'll likely need to modify this script to run your package's usual build
flow, since packages use many different workflows and directory structures.
This is the ideal place to invoke anything which is normally part of *your app's
build process*: anything that you need to transform your project's source code
into a runnable deployment, but explicitly *not* the project's deployment,
configuration, or user data.
Usually you put things here which should be run again as the result of changes
to your project's source code. Examples of things you might put here are:
- Compiling your project from source, for projects written in compiled languages.
- Calling `composer` to install or update PHP dependencies described in your app's `composer.json`
- Calling `pip` to install your app's Python-specific dependencies from the `requirements.txt` in your app's repository
- Calling `npm install` to install or update npm dependencies from your app's `package.json`
- Calling `bower install` to install or update web/css dependencies described in the app's `bower.json`
- Calling `gulp` to compile and minify SASS/LESS into CSS, or collect javascript into bundles
- Minifying dependencies
- Collecting various build artifacts or assets into a deployment-ready directory structure
### launcher.sh
This script will be run every time an instance of your app - aka grain - starts
in Sandstorm. It is run inside the Sandstorm sandbox. This script will be run
both when a grain first launches, and when a grain resumes after being
previously shut down. This script is responsible for *launching everything that
your app needs to run*. The thing it should do *last* is:
- start a process in the foreground listening on port 8000 for HTTP requests.
Frequently this is something like `nginx` serving static files and reverse
proxying for some other backend service. You want to run this last because
accepting requests on port 8000 is how you signal to the Sandstorm platform
that your application is completely up and ready for use. If you do this
before your backend is ready to go, users could get e.g. 502 errors or see a
broken page on first load - a poor first experience.
Other things you probably want to do in this script include:
- Building folder structures in `/var`. `/var` is the only non-tmpfs folder mounted R/W, and when a grain is first launched, it will start out empty. It will persist between runs of the same grain, but be unique per app instance.
- Preparing a database and running migrations. You can also manually generate some tables once, place them somewhere under `/opt/app`, and copy them to `/var/lib/mysql` if your app takes a while to do migrations, at the potential cost of producing a larger `.spk`.
- Launching other daemons that your app uses (`mysqld`, `redis-server`, `php5-fpm`, `uwsgi`, etc.)
For apps which need the ability to self-modify code or configuration, or which
expect to be able to write data underneath their source tree, you
should create a dangling symlink from
`/opt/app/where-your-app-keeps-its-self-modifiable-config.conf` to somewhere
under `/var`, then copy or generate a default configuration to that symlink target under `/var` in
`launcher.sh` so your app will find it at runtime.
There's an example of this in the paperwork repository -
[`build.sh`](https://github.com/JamborJan/paperwork/blob/cf4b11631e9cda9d45196b1a545a116376e630af/.sandstorm/build.sh#L35)
removes the folder `frontend/app/storage` and replaces it with a symlink
pointing to `/var/storage`. Then,
[`launcher.sh`](https://github.com/JamborJan/paperwork/blob/cf4b11631e9cda9d45196b1a545a116376e630af/.sandstorm/launcher.sh#L16-24)
makes sure that `/var/storage` exists and is populated with the appropriate
subdirectories.
These tend to be unique per-app, so again, `vagrant-spk` provides appropriate
defaults for common stacks, but you'll likely need to make adjustments for your
app.
### sandstorm-files.list
This file is generated by running `vagrant-spk dev` and using the app. It contains a list
of all files that your app used at runtime. This is used to construct a
minimal package. See
https://github.com/sandstorm-io/sandstorm/wiki/Porting-an-app-with-vagrant-spk
In the fullness of time, we'd like to support a method of generating
`sandstorm-files.list` that doesn't require the developer to carefully use
every app feature to make sure that e.g. default plugins get included in the
package.
### sandstorm-pkgdef.capnp
See https://github.com/sandstorm-io/sandstorm/wiki/Porting-an-app-with-vagrant-spk
### Vagrantfile
See https://github.com/sandstorm-io/sandstorm/wiki/Porting-an-app-with-vagrant-spk
## Example setups
### Default setup
Repo: https://github.com/paulproteus/php-app-to-package-for-sandstorm
This example shows how to setup a php + mysql app.
`setup.sh` installs PHP, nginx, and MySQL from the distribution's repository,
then modifies default config files to support the `/opt/app` layout and run
in the Sandstorm sandbox.
`build.sh` installs/updates composer, and uses composer to install PHP
dependencies.
`launcher.sh` creates a folder structure in `/var` for MySQL, nginx, and
php5-fpm, creates MySQL tables, then launches the three daemons, checking that
`mysqld` and `php5-fpm` are ready to accept requests before launching `nginx`,
which will listen for requests on port 8000.
### Paperwork (php, mysql, composer, npm)
Repo: https://github.com/JamborJan/paperwork
[`setup.sh`](https://github.com/JamborJan/paperwork/blob/master/.sandstorm/setup.sh)
installs PHP, nginx, nodejs, and npm. Additionally, it installs some
system-global tools (`gulp` and `bower`) with `npm`.
[`build.sh`](https://github.com/JamborJan/paperwork/blob/master/.sandstorm/build.sh)
does several things: it installs and updates `composer`, installs app-specific
`npm` and `bower` dependencies from `package.json` and `bower.json` manifests
in the repo, and runs `gulp` to build static assets.
[`launcher.sh`](https://github.com/JamborJan/paperwork/blob/master/.sandstorm/launcher.sh)
creates the storage folders for notes in `/var/storage`, which the app will
find because `/opt/app/frontend/app/storage` (the standard storage location for
Paperwork) is a symlink to `/var/storage`. Additionally, the script sets up
the default database, grants permissions, and runs migrations.
docs/vagrant-spk/index.md
+11
View File
@@ -0,0 +1,11 @@
# vagrant-spk
The goal of `vagrant-spk` is to be an easy-to-install tool that runs on
Windows, Mac, and Linux that lets people create Sandstorm packages
without mucking with their main operating system.
Right now it works properly on Mac and GNU/Linux systems. Windows
support is forthcoming.
Use the navigation at the top of the screen to navigate the
`vagrant-spk` documentation.
docs/vagrant-spk/installation.md
+128
View File
@@ -0,0 +1,128 @@
# Installation
Before we install `vagrant-spk`, some advice for how to succeed at the
installation process.
* Learn about Sandstorm, if you haven't already. [Try using Sandstorm at our demo server](https://demo.sandstorm.io) 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](https://git-scm.com/download/mac) 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](http://vagrantup.com/) 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
(C) 2005-2015 Oracle Corporation
All rights reserved.
```
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](https://www.virtualbox.org/wiki/Downloads)
* 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`
Finally, you can install `vagrant-spk` itself. 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.)
docs/vagrant-spk/packaging-tutorial.md
+292
View File
@@ -0,0 +1,292 @@
# Packaging tutorial
Style: Hands-on introductory tutorial.
This tutorial will show you how to package an app for
[Sandstorm](https://sandstorm.io) 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](https://github.com/sandstorm-io/sandstorm/wiki/Sandstorm-App-Developer-Handbook).
## Before proceeding, install vagrant-spk
Make sure you've worked through the
[vagrant-spk installation guide](installation.md) before going through this tutorial!
# 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 Sandstorm 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`? How do I make `vagrant-spk` faster?
Read about [understanding & customizing vagrant-spk](customizing.md).
* How do I package-up a Python, Meteor, or other non-PHP app? Read about [platform stacks](platform-stacks.md).
* Will this work on Windows? No, not yet. Sorry, we're working on it.
* Will this work if I typically run Sandstorm-related programs in a virtual machine? We don't know, but we hope so.
docs/vagrant-spk/platform-stacks.md
+60
View File
@@ -0,0 +1,60 @@
# Platform stacks
## About platform stacks
`vagrant-spk` includes support for a number of programming languages
and/or web frameworks, each of which have different practices on how
to go from the app's source code to a running web server.
Running this command:
```
vagrant-spk setupvm platformname
```
will set up a Linux virtual machine (with Sandstorm installeed) ready to
run code in the platform called `platformname`.
This page contains **reference documentation** you might use after
having gone through the main [vagrant-spk packaging
tutorial](packaging-tutorial.md).
## DIY platform stack
`diy` in this platform stack stands for do-it-yourself. It provides
just the basic scripts, and requires you to fill in the
various `.sandstorm/` scripts.
This platform stack is for you if you want to package an app for
Sandstorm with `vagrant-spk` where there is no platform stack for
the framework/library/platform the app was written against, or if
you want a minimal platform stack because you know what you're doing.
See [Customizing & understanding vagrant-spk](customizing.md) for
details.
## Meteor platform stack
### 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!
**Troubleshooting**
If the app fails at the `vagrant-spk dev` step due to a packaging
error, you may need to:
```bash
meteor remove-platform ios
meteor remove-platform android
```
and then retry the `vagrant-spk dev` step.
mkdocs.yml
+12
View File
@@ -0,0 +1,12 @@
site_name: Sandstorm
pages:
- "Home": "index.md"
- Intro:
- "Overview": "overview.md"
- "Installation": "install.md"
- vagrant-spk:
- "Overview": "vagrant-spk/index.md"
- "Installation": "vagrant-spk/installation.md"
- "Packaging tutorial": "vagrant-spk/packaging-tutorial.md"
- "Understanding & customizing": "vagrant-spk/customizing.md"
- "Platform stacks": "vagrant-spk/platform-stacks.md"