Rancher Catalog Templates from Scratch : Part 1 - Catalogs and Templates

An edited version of this post also appeared on the Rancher Labs blog.

Rancher ships with a number of re-usable pre-built application stack Templates. Learning to extend these Templates or to create and share completely new Templates are two 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 to this point documentation on how to get started as a new Catalog Template author has consisted of only a single high-level blog post: Building Rancher Catalog Templates.

This article is the first in a series aimed at helping the new Catalog Template author ramp-up quickly and with the best available tooling and techniques.

For the first article in the series we are going to construct a very simple, and not terribly useful ;), Cattle Catalog Template. In upcoming article we will flesh out this Template with more detail until we have a working multi-container NGINX-based static web site utilizing all of the basics of Rancher Compose, Docker Compose, and Rancher Cattle.

Overview & Terminology

Before we dive into the process of creating a new Rancher Catalog let's first get some common terminology out of the way. If you are an experienced Rancher user you may be able to just 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 Google-ing.

For our purposes, Rancher is Open Source software enabling deployment and lifecycle management of container-based applications stacks using most of the commonly available Open Source container orchestration frameworks. As of the time 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 ( 1]

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 prebuilt and re-usable 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 which compose the Stack.

Screenshot of the available application Templates in the Rancher Cattle Catalog

Each orchestration framework ships with a set of pre-built Catalog Templates. In this article we are going to focus on just Rancher's own Cattle orchestrator. See the image below for examples of some of the many pre-built Catalog Templates which ship for Cattle.

Screenshot of the Rancher admin Console with running application Stacks

Creating your first Rancher Cattle Catalog Template

Many times these 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 perhaps even create a new Template from scratch when your desired application stack does not already have a Template.

Doing it manually

For the purposes of this exercise I'm going to 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 for some setup of our working directory on our local workstation:

Screenshot of local workstation setup for 'demo' Template

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:

Screenshot of initial git commit & push of our 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:

Screenshot of initial push to GitHub

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:

Screenshot of Admin/Settings in Rancher admin console

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.

Screenshot of adding a new Catalog repo

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...

Screenshot of 'demo app' Catalog with incomplete Template

We've successfully created the scaffolding for a Rancher Cattle Template but we've not populated any of the metadata for our Template nor for the definition and 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!) so we're going to punt that for now and focus on just basic metadata for the Template. In other words, 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.


The config.yml is primarily the 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:

Screenshot of improved demo Template

That's starting to look a lot better but out Catalog Template still doesn't do anything useful. We'll cover how to define our application stack in the next blog post in this series. (HINT: It involves population of 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...

While creating new Catalog Templates manually, as we have done above, doesn't require any deep magic its easy to make a small and silly mistake which results in an error. In fact, in going through the process while writing this post I made several small mistakes which resulted in having to repeat the process for generating screenshots. It would be excellent if there were tooling which would allow us to create new Catalog Templates in a fast, repeatable, low-probability-or-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 show below:

Animated GIF of creating a new Cattle Catalog Template with Yeoman


Comments powered by Disqus