Using Docker Compose Files to define RancherOS System Services

Gray Calendar Icon Published: September 30, 2015
Gray Calendar Icon Updated: November 13, 2019

docker compose -
rancherOSHello, I’m Ivan Mikushin (@imikushin), one of the developers here at Rancher working on RancherOS. Today I wanted to walk you through the concept of RancherOS \“system services.\” As you may know, RancherOS was designed from the ground up to run everything above the kernel as Docker containers, allowing simple upgrades and a tiny OS footprint. The goal of RancherOS is to provide the perfect small OS for running Docker containers. One of the first things you realize when deploying applications or infrastructure workloads as containers, is the need for support containers that provide secondary functions beyond the primary purpose of the host. We think of these support containers as \“system services\“, and they can be almost anything. A good example would be a monitoring or security agent, or perhaps a key value store. These system services often need to start before the application workload, and they might need to run at the system level, as opposed to the user level. So we wanted to come up with a way to define the start-order, as well as determine whether a service runs on the system or user docker daemon. As you might imagine with a Docker focused OS, we looked at existing Docker projects, and decided to use Docker Compose to define application deployment. Beginning with release of RancherOS v0.3.1, we started using Docker Compose files (compose.yml) to define system services. In the example below I’m creating a simple container logging service based on logspout which monitors container logs and sends them to a remote syslog service (e.g. using Papertrail):

  image: gliderlabs/logspout
  command: syslog://  # send logs to my PaperTrail dashboard :)
  restart: always
  net: host  # use the host's network (instead of NATed container network)
  uts: host  # use the host's hostname
  - io.rancher.os.scope=system  # sets the container to be run in system-docker (instead of docker)
  - /var/run/docker.sock:/tmp/docker.sock

This compose template defines a log capturing service (named \“logspout-papertrail\“) and illustrates how you can have RancherOSa run a service by system-docker using `io.rancher.os.scope=system` label. We’re bind-mounting `/var/run/docker.sock`from the host into the logspout container, so that it can communicate with the \“user\” docker daemon on the host and capture all application containers’ logs. You can publish this file via HTTP(S) and provide the link to RancherOS:

sudo ros s enable $COMPOSE_URL

RancherOS will launch enabled services on boot. To check what’s enabled, type:

ros s list

and the output will look similar to this:

disabled debian-console
enabled  ubuntu-console

If you’re launching RancherOS with cloud-config (for example, on Amazon EC2 by entering user data when launching an instance), you can enable system services in the cloud-config YAML like this:

  services_include: true

Make sure you use a real URL to your compose template :) RancherOS system services documentation article provides details on service linking and difference between system services (run by system-docker) and user services (run by regular docker). Over the next week or so we’ll be demonstrating a few examples of system services. If you’re interested in learning more, you can download RancherOS on GitHub, or request a discussion with one of our engineers for a RancherOS demo.

Get started with Rancher