Building Rancher Docker Container Catalog Templates from Scratch : Part 1

Rancher ships
with a number of reusable, pre-built application stack templates.
Extending these templates or creating and sharing completely new ones
are great ways to participate in the Rancher user community and to help
your organization effectively leverage container-based
technologies. Although the Rancher documentation is
fairly exhaustive, so far documentation on how to get started as a new
Catalog template author has consisted of only a single high-level blog
post. This
article is the first in a series aimed at helping the new Catalog
template author ramp-up quickly, with the best available tooling and
techniques. For the first article in this series, we are going to
construct a very simple (and not terribly useful) Cattle Catalog
template. In an upcoming article, we will flesh out this template with
more detail until we have a working multi-container NGINX-based static
website utilizing all of the basics of Rancher Compose, Docker Compose,
and Rancher Cattle.

[Overview and Terminology]

Before we dive into creating a new Rancher Catalog template, let’s
first get some common terminology out of the way. If you are an
experienced Rancher user, you may be able to scan through this section.
If you are new to the world of Linux
containers, cluster
managers, and container
orchestration, now is
a good time to do some Googling. For our purposes, Rancher is Open
Source software enabling deployment and lifecycle management of
container-based application stacks, using most of the commonly available
Open Source container orchestration frameworks. As of this writing,
Rancher has excellent support for Docker containers and the following
orchestration frameworks:

• Kubernetes
  (1,
  2)
• Mesos (1,
  2)
• Docker Swarm (1,
  2)
• Rancher’s own Docker Compose-based Cattle

If your favorite framework isn’t listed rest assured, that support is
probably on the way. Within the context of each of the previously
mentioned orchestration frameworks, Rancher includes a catalog of
pre-built and reusable application templates. These templates may be
composed of a single container image, but many times they stitch
together multiple images. Templates can be fed environment-specific
configuration parameters and instantiated into running application
stacks via the Rancher admin console. The screenshot below shows several
applications stacks as viewed via the Rancher admin console. Note that
the WordPress and
Prometheus stacks are expanded to show the
multiple containers comprising each stack.
In this article, we are going to focus on Rancher’s own Cattle
orchestrator. See the image below for examples of some of the many
pre-built Catalog templates which ship for Cattle.

###

Creating your first Rancher Cattle Catalog template

Many times these pre-built Rancher Catalog templates can be used as
shipped, but sometimes you’ll need to modify a template (and please
then submit your pull request to the upstream!), or even create a new
template from scratch when your desired application stack does not
already have one.

Doing it manually

For the purposes of this exercise, I’ll assume you have:

(1) a container host running the rancher/server container (2) at least
one compute node running rancher/agent (for the purposes of the demo,
(1) and (2) can be the same host) (3) a configured Rancher Cattle
environment (available by default with a running rancher/server
instance)

If that is not the case, please check out the one of the Rancher
Overview videos on the Rancher Labs YouTube
channel.

Adding a custom Cattle Catalog template

By default, the Catalog templates listed in the Rancher admin console
are sourced from the Rancher Community Catalog
repository. We’ll create
our own git repo as a source for our new ‘demo app’ Cattle Catalog
template. First, we’ll set up our working directory on our local
workstation:
Although there’s no deep magic, let’s step through the above:

1. Create a project working directory named ‘rancher-cattle-demo’
   under ~/workspace. These names and paths are fairly arbitrary
   though you may find it useful to name the working directory and git
   repo according to the following convention: rancher-<orchestration
   framework>-<app name>.
2. Create the git repo locally with ‘git init’ and on
   GitHub via the
   ‘hub’ utility.
3. Populate the repo with a minimal set of files necessary for a
   Rancher Cattle Catalog template. We’ll cover this in detail in a
   second.

Now let’s do our initial commit and ‘git push’ of the demo template:

For sanity’s sake, you might want to check that your push to GitHub was
successful. Here’s my account after the above push:
It’s worth noting that in the above screenshot I’m using the
Octotree
Chrome extension to get a full filesystem view of the repo. Now let’s
configure Rancher to pull in our new Catalog template. This is done via
the Rancher admin console under Admin/Settings:
Click the “+” next to “Add Catalog” near the middle of the page.
Text boxes will appear where you can enter a name and URI for the new
Catalog repo. In this case, I’ve chosen the name ‘demo app’ for our
new Catalog repo. Note the other custom Catalog settings from previous
custom work.
Now we can go to Catalog/demo app in the Rancher admin console and pull
see the listing of container templates. In this case, just our ‘demo
app’ template. But wait there’s something wrong…
We’ve successfully created the scaffolding for a Rancher Cattle
template, but we’ve not populated any of the metadata for our template,
nor the definition or configuration of our container-based app. The
definition of our application via docker-compose.yml and
rancher-compose.yml is worthy or its own blog post (or two!), but for
now we’ll focus on just basic metadata for the template. In other words,
we’ll look at just the contents of config.yml

Minimal config.yml

The Rancher documentation contains detailed
information about config.yml. We’re going to do just enough to get
things working, but a thorough read of the docs is highly recommended.

config.yml

The config.yml file is the primary source of metadata associated with
the template. Let’s look at a minimal example:

---
name: Demo App
description: >
  A Demo App which does almost nothing of any practical value.
version: 0.0.1-rancher1
category: Toy Apps
maintainer: Nathan Valentine <nathan@rancher.com|nrvale0@gmail.com>
license: Apache2
projectURL: https://github.com/nrvale0/rancher-cattle-demo

In case it wasn’t evident from the filename, the metadata is specified
as YAML. Given the above YAML and the Icon file present in this git
commit,
let’s look at the new state of our template:
That’s starting to look a lot better, but our Catalog template still
doesn’t do anything useful. In our next post in this series, we’ll cover
how to define our application stack (Hint: it involves populating the
docker-compose.yml and rancher-compose.yml files.)

A better way to create templates

Before we move on to definition of our application, I need to tell you a
secret… When creating new Catalog templates manually doesn’t require
any deep magic, it’s easy to make a small and silly mistake which
results in an error. It would be excellent to have tooling that allowed
us to create new Catalog templates in a fast, repeatable,
low-probability-of-error way…and in fact there is. The Rancher
community has submitted a Rancher Catalog Template
‘generator’
to The Yeoman Project. Assuming you have a working
Node.js environment, generating a new Cattle Catalog Template with
default scaffolding is as simple as the process shown below: