Gilliam makes sure your processes are running.

The model is quite simple and flexible: Services are grouped in formations. Code is built into an image and combined with configuration to form a release. From this release instances are created and Gilliam will make sure that they keep running.


A formation ties together some business logic with its dependencies into a named group. Everything is a service, either exposed to other services and formations, or internal. Examples of internal services are databases and caches.

In micro service architectures a service is really small and perform a single task.


The builder is responsible for taking code and bundling it with its dependencies and run-time into an image.

When the gilliam deploy command is issued the complete source tree of the service will be tar:ed up and sent to the builder, which will feed it into a buildpack. Its up to the buildpack to gather dependencies and prepare the image. When done, the whole thing is assembled into an image and a new release is created for the service.

Gilliams architecture do not require a special build server, but the builder is a convenient way of creating images and releasing them. One can envision other ways of getting code into a release; git push or maybe a Jenkins job.


Borrowing from dotCloud, the gilliam.yml file defines services that will live in your formation. Each service has a type, which specifies how it will be built and deployed. If not specified, services default to the custom type which will try to build the service using a Buildpack.

Services run in resource constrained, isolated, ephemeral environments provided by the hypervisor. If services need to share or persist state it should be done outside of the container, like in a database or a cache.


The scheduler is the heart of Gilliam. It is the component that is make sure that the desired number of instances are running for your services. It constantly talks to the executors and monitor their state.

Instances are currently spread in a random fashion over all executors.

The scheduler provides a simple RESTful API to manage formations, releases and instances. This is the API that gilliam uses when you issue migrate or scale commands.


A custom service is built, with all its runtime dependencies, into an immutable Docker image. The image will be pushed to a registry. Later, when an instance is spawned or migrated, the image will get pulled into the executor and launched.

Gilliam doesn't care if you store your images on a private registry or on the offical Docker one.


This is the component that actually executes your code. It is mostly an API around a Docker daemon, but it also provides some functionality that is essential to the platform. Like logging and the HTTP proxy that allows services to easily talk to other services without having to integate with any platform-specific libraries or tools.


The platform doesn't really dictate how configuration is managed, but it is encouraged to use environment variables.

Auxiliary Services

Databases, caches and other internal services that are not your own are called auxiliary services. These services are not different in any way, expect that they should not be exposed outside of the formation.


A release is the combination of code and environment, and it is the thing that is actually deployed. A new release is created every time new code is pushed or when environment variables is changed.

By being the deployable unit, it is on a release that you set scale factors. This means that it is possible to have multiple releases deployed at the same time, allowing partial and gradiual roll out of changes.

Scale Factors

Scale factors are set on a release and will instruct the scheduler to try to make sure that the specified number of instances for each service is always running.