Build and run apps on OSv using Capstan

Prerequisites

You will have the best experience following this guide on Linux in terms of performance. It is also possible to build and run OSv apps on Mac/OSX, however running apps will be significantly slower due to lack of KVM accelerator.

Alternatively, it is possible to run OSv on Mac on VirtualBox which should yield much better performance than QEMU. However, the images produced by capstan need to be converted to vbox/vmdk format.

Steps:

• Install capstan by manually downloading the relevant binary from the latest Github release assets page
• Install QEMU/KVM

# On Ubuntu
sudo apt-get install qemu-system-x86 qemu-utils

# On Fedora
sudo yum install qemu-system-x86 qemu-img

# On Mac OSX
brew install qemu

Instead of manually installing capstan and qemu, you can use the unofficial Docker project that comes with many OSv app examples.

Build and run steps

1. Create an app directory and under it initialize capstan app package using following command example (make sure capstan is present in your PATH):

capstan package init \
  --name "java-example" \
  --title "Java Example" \
  --author "Anonymous" \
  --version "1.0" \
  --require "osv.openjdk10-java-base" \
  --require "osv.run-java"

This will generate a YAML file under meta/package.yaml looking like so:

name: my-first-osv-app
title: Java Example
author: Anonymous
version: "1.0"
require:
- osv.openjdk10-java-base
- osv.run-java

A java app like an example above requires both OpenJDK JRE as well as run-java packages. For Node, Python and Golang examples please see this.

2. Add your application files to the project folder. Depending on the language/framework you will end up using whatever your app build tool is like make, gradle, maven (Java echosystem), grunt, webpack (Node.JS), etc. All the app files added to your project directory will end up at the root of OSv filesystem in the image. ⋅⋅⋅If you want to skip some files please add .capstanignore with the list of files and directories you do not want to be part of OSv image.

3. Fuse the application OSv image by running the following:

capstan package compose --pull-missing java-example #Or whatever name of your app is

This capstan command reads meta/package.yaml and optional meta/run.yaml files (for more details see this) in order to pull any missing packages on your local filesystem from OSv Github repo or S3 bucket (the capstan packages are actually tar archives so you can look up their content under $HOME/.capstan/packages). Then it untars the required packages along with the kernel and fuses all files into final OSv QCOW2 image found under $HOME/.capstan/repository/[app-package-name].

4. Finally run your application by running following:

capstan run java-example -p qemu --boot default