Helios Circle CI Slack Status Download

Status: Bug-fix only

This project was created when there were no open source container orchestration frameworks. Since the advent of Kubernetes and other tools, we've stopped adding new features to helios and are now switching to other tools like Kubernetes. This project will no longer have new features or accept PRs for new features. We will continue to accept bug fixes, however.

Helios is a Docker orchestration platform for deploying and managing containers across an entire fleet of servers. Helios provides a HTTP API as well as a command-line client to interact with servers running your containers. It also keeps a history of events in your cluster including information such as deploys, restarts and version changes.

Usage Example

# Create an nginx job using the nginx container image, exposing it on the host on port 8080
$ helios create nginx:v1 nginx:1.7.1 -p http=80:8080

# Check that the job is listed
$ helios jobs

# List helios hosts
$ helios hosts

# Deploy the nginx job on one of the hosts
$ helios deploy nginx:v1 <host>

# Check the job status
$ helios status

# Curl the nginx container when it's started running
$ curl <host>:8080

# Undeploy the nginx job
$ helios undeploy -a nginx:v1

# Remove the nginx job
$ helios remove nginx:v1

Getting Started

If you're looking for how to use Helios, see the docs directory. Most probably the User Manual is what you're looking for.

If you're looking for how to download, build, install and run Helios, keep reading.


The binary release of Helios is built for Ubuntu 14.04.1 LTS, but Helios should be buildable on any platform with at least Java 8 and a recent Maven 3 available.

Other components that are required for a helios installation are:

Install & Run

Quick start for local usage

Use helios-solo to launch a local environment with a Helios master and agent.

First, ensure you have Docker installed locally. Test this by making sure docker info works. Then install helios-solo:

# add the helios apt repository
$ sudo apt-key adv --keyserver hkp://keys.gnupg.net:80 --recv-keys 6F75C6183FF5E93D
$ echo "deb https://dl.bintray.com/spotify/deb trusty main" | sudo tee -a /etc/apt/sources.list.d/helios.list

# install helios-solo on Debian/Ubuntu
$ sudo apt-get update && sudo apt-get install helios-solo

# install helios-solo on OS X
$ brew tap spotify/public && brew install helios-solo

Once you've got it installed, bring up the helios-solo cluster:

# launch a helios cluster in a Docker container
$ helios-up

# check if it worked and the solo agent is registered
$ helios-solo hosts

You can now use helios-solo as your local Helios cluster. If you have issues, see the detailed helios-solo documentation.

Production on Debian, Ubuntu, etc.

Prebuilt Debian packages are available for production use. To install:

# add the helios apt repository
$ sudo apt-key adv --keyserver hkp://keys.gnupg.net:80 --recv-keys 6F75C6183FF5E93D
$ echo "deb https://dl.bintray.com/spotify/deb trusty main" | sudo tee -a /etc/apt/sources.list.d/helios.list

# install Helios command-line tools
$ sudo apt-get install helios

# install Helios master (assumes you have zookeeperd installed)
$ sudo apt-get install helios-master

# install Helios agent (assumes you have Docker installed)
$ sudo apt-get install helios-agent

Note that the Helios master and agent services both try to connect to ZooKeeper at localhost:2181 by default. We recommend reading the Helios configuration & deployment guide before starting a production cluster.

Manual approach

The launcher scripts are in bin/. After you've built Helios following the instructions below, you should be able to start the agent and master:

$ bin/helios-master &
$ bin/helios-agent &

If you see any issues, make sure you have the prerequisites (Docker and Zookeeper) installed.

Build & Test

First, make sure you have Docker installed locally. If you're using OS X, we recommend using docker-machine.

Actually building Helios and running its tests should be a simple matter of running:

$ mvn clean package

For more info on setting up a development environment and an introduction to the source code, see the Developer Guide.

How it all fits together

The helios command line tool connects to your helios master via HTTP. The Helios master is connected to a Zookeeper cluster that is used both as persistent storage and as a communications channel to the agents. The helios agent is a java process that typically lives on the same host as the Docker daemon, connecting to it via a Unix socket or optionally TCP socket.

Helios is designed for high availability, with execution state being confined to a potentially highly available Zookeeper cluster. This means that several helios-master services can respond to HTTP requests concurrently, removing any single point of failure in the helios setup using straight forward HTTP load balancing strategies.

Production Readiness

We at Spotify are running Helios in production (as of October 2015) with dozens of critical backend services, so we trust it. Whether you should trust it to not cause smoking holes in your infrastructure is up to you.

Why Helios?

There are a number of Docker orchestration systems, why should you choose Helios?

Other Software You Might Want To Consider

Here are a few other things you probably want to consider using alongside Helios:


To run findbugs on the helios codebase, do mvn clean compile site. This will build helios and then run an analysis, emitting reports in helios-*/target/site/findbugs.html.

To silence an irrelevant warning, add a filter match along with a justification in findbugs-exclude.xml.

The Nickel Tour

The sources for the Helios master and agent are under helios-services. The CLI source is under helios-tools. The Helios Java client is under helios-client.

The main meat of the Helios agent is in Supervisor.java, which revolves around the lifecycle of managing individual running Docker containers.

For the master, the HTTP response handlers are in src/main/java/com/spotify/helios/master/resources.

Interactions with ZooKeeper for the agent and master are mainly in ZookeeperAgentModel.java and ZooKeeperMasterModel.java, respectively.

The Helios services use Dropwizard which is a bundle of Jetty, Jersey, Jackson, Yammer Metrics, Guava, Logback and other Java libraries.

Community Ideas

These are things we want, but haven't gotten to. If you feel inspired, we'd love to talk to you about these (in no particular order):