Command line interface for vorteil.io kernel
Go Other
Latest commit 56f8b01 Oct 20, 2017 @alankm alankm .

README.md

Vorteil

License: Apache 2.0

The lightweight Vorteil Kernel is used to compile Go apps into bootable virtual disks for microservices and immutable infrastructure. Using a unikernel approach, the Vorteil Kernel has virtually zero run-time overhead and boots up in a matter of milliseconds.

vorteil.io in action:

Booting vorteil

Vorteil CLI

The Vorteil Command-Line Interface (vcli) is the only tool you'll ever need to develop, test, build, and deploy vorteil-os applications for the cloud.

Installation.

LINUX

!> We recommend you install QEMU before installing vcli.

Ubuntu

Run the following commands to install vcli with apt.

curl -s https://packagecloud.io/install/repositories/sisatech/vcli/script.deb.sh | sudo bash && sudo apt install vcli
sudo apt install vcli

Verify the installion worked by running a vcli command.

vcli version

Other

Download the linux-amd64 binary from the latest github release.

Rename the file to vcli, chmod it to make it executable, and move it somewhere on the PATH.

Verify the installion worked by running a vcli command.

vcli version

Mac

!> We recommend you install VirtualBox before installing vcli.

Download the osx-amd64 binary from the latest github release.

Change the permissions of that file to make it executable and copy into a folder, which is in the PATH environment variable.

chmod 755 ~/Downloads/vcli-X.Y.Z-osx-amd64
sudo cp ~/Downloads/vcli-X.Y.Z-osx-amd64 /usr/local/bin/vcli

Verify the installion worked by running a vcli command.

vcli version

Windows

!> We recommend you install VirtualBox before installing vcli.

Download vcli.exe from the latest github release.

Move vcli.exe somewhere on the Path system variable.

Verify that vcli works by running a command.

vcli version

Quickstart

Running your first Vorteil App

!> Follow the Installation instructions for your operating system first.

VCLI (Vorteil Command-Line Interface) is the primary tool you'll need to work with Vorteil. Let's dive in and see how easy it is to start using VCLI. To keep things simple, we'll download a simple Hello World application from Sisa-Tech's online repository.

Get a Vorteil App

vcli pull sisatech/helloworld

This command connects to Sisa-Tech's online Vorteil Apps Marketplace and downloads the pre-prepared helloworld package into your current directory. Vorteil Packages can be identified by their ".vorteil" file extension, so after you run this command you should see helloworld.vorteil in your current directory.

Run a Vorteil App in a Virtual Machine

vcli run

Vorteil packages contain everything VCLI needs to build and start a Virtual Machine running an application on the Vorteil Kernel. The helloworld application we downloaded is designed to run a simple "Welcome to Vorteil" webpage listening on port 8888. Once your virtual machine is up and running, check if the application is working by visiting localhost:8888.

Hello World

When you're finished, use 'CTRL+C' in the terminal running VCLI, or close the virtual machine manually to close the application. See the FAQ.

Building your own Vorteil App

Let’s do something a bit more interesting. There’s nothing special about the application we’re running inside the helloworld package: it simply needs to be a binary compiled for linux. In fact, if you unpack this package and run the helloworld binary from the terminal you’d see exactly the same behaviour as you just saw on the virtual machine (if you’re using Linux).

VCLI makes it easy to build your own Vorteil App. To keep things simple, we'll demonstrate this by just making a small change to the runtime environment provided by Vorteil to the helloworld application so that we don’t have to worry about changing any code or cross-compiling for Linux if you’re on Windows or Mac.

Unpacking the helloworld package

vcli unpack

VCLI's unpack command will extract all of the files contained within the helloworld.vorteil package to a new directory called "helloworld", making them available for us to modify. Inside you should see the following:

  • helloworld: the Linux binary that Vorteil will run
  • helloworld.files: a directory containing all of the files that will be built onto the filesystem of the virtual machine disk
  • helloworld.vcfg: a YAML configuration file containing information VCLI uses when building the virtual machine disk
  • vorteil.png: an icon for the package

Changing the runtime environment

The helloworld program was designed to set the background of the “Welcome to Vorteil” webpage to the colour stored in the BACKGROUND environment variable. Let's change the colour from white to black.

Open “helloworld/helloworld.vcfg” in your preferred text editor. Inside you should see a section containing the following:

env:
  vars:
    BACKGROUND: "0xFFFFFF"

Replace it with the following:

env:
  vars:
    BACKGROUND: "0x000000"

Save and close the configuration file.

Test run non-packaged files

vcli run helloworld

VCLI isn’t just capable of running packages, it can also assemble the information it needs from unpackaged files. Use the “vcli run” command like you did before, but this time make sure to target the unpacked files, not the helloworld package from before. Try running “vcli run helloworld”, which tells VCLI to use the files within the “helloworld” directory. Once your virtual machine is up and running, check if the application is working by visiting http://localhost:8888/.

When you're finished, use 'CTRL+C' in the terminal running VCLI, or close the virtual machine manually to close the application. See the FAQ.

Now that you’ve seen your changes working locally, it’s time to get it online and on The Internet. We’ve provided an online platform just for Vorteil applications at go-vorteil.io for this very purpose.

Package your modified application

vcli package helloworld --icon helloworld/vorteil.png

Before we can upload or distribute our file to we’ll need to re-package it with our changes. Use “vcli package helloworld” to generate a new package from the modified files in your “helloworld” directory. This will overwrite the original package “helloworld.vorteil” unless you renamed it earlier.

Uploading your Vorteil App

Open your preferred web browser and navigate to https://go-vorteil.io. Log in or sign up as neccessary. If this is your first time logging in to your vorteil.io account, you will be prompted to create a new organisation.

vorteil.io - Applications

Once logged in, you will be redirected to the 'Applications' page. From here, we can upload our package. Click the blue 'upload' icon in the top-right of the webpage.

vorteil.io - Upload Application

Enter a name to list your application under, and 'hellworld.vorteil'. Click the 'Upload' button to proceed.

Deploy your Vorteil App

vorteil.io - Details Button

Once your application has been successfully uploaded, it will appear on your Applications page. Mouse over the 'actions' icon displayed to the right of your application, and click the '...' button to see visit the 'Details' page.

vorteil.io - Details

The 'Details' page displays the application's configuration, and allows the user to perform a number of different actions. Click on the green 'Actions' button, and select 'Deploy' from the dropdown menu.

vorteil.io - Deploy Modal

From here, we configure our new deployment. Select a name, and add a platform. All users receive free limited access to the vortlie.io default platform, 'VMS'. Select this platform, and set your deployment to spawn 1 instance of your application. When satisfied with your settings, click the 'Deploy' button. This will redirect you to a page for your new deployment.

vorteil.io - Deployment

The 'Deployment' page allows you to monitor and adjust a deployment, and displays helpful performance metrics gathered from your deployed instances.

vorteil.io - URLs

Click the link listed underneath the main title for your deployment.

vorteil.io - HelloWorld