With the announcement of private catalog support in the Rancher platform we decided to create a custom catalog for our application stack.

If you are looking for a complete overview and step by step on how to create a private catalog the best place is the January online meetup Building a Docker Application Catalog

In the post I'll guide you through the steps I took to create a catalog for our application, the Aytra Cloud.

The main concepts behind a Catalog on Rancher are

  • Expose docker and rancher compose frameworks to define a catalog blueprint
  • Store templates on git repo
  • Allow configuration and deployment of stacks
  • Support versioning and upgrades

Creating the Catalog file structure

So in a nutshell you will need to have a git repo with the following directory structure

In the config.yml file you can define the basic configuration for you catalog, eg;

name: Aytra  
description: |  
  Aytra Cloud enables our customers to fully realize the potential of cloud computing by allowing them to automatically migrate application workloads across public and private clouds to achieve an ideal balance of security, cost, and performance.
version: 7.5  
category: "Cloud Management Platform"  

To define different versions of the same catalog Rancher uses the concept of numbered directories containing different versions of a docker-compose and rancher-compose templates.

One point to note about the rancher-compose file is that a .catalog section must be defined as well as a questions attribute, for example:

.catalog:
  name: Aytra
  version: 7.5
  description: |
    Aytra Cloud enables our customers to fully realize the potential of cloud computing by allowing them to automatically migrate application workloads across public and private clouds to achieve an ideal balance of security, cost, and performance.
  uuid: aytra-0
  questions:
    - variable: "exo-scale"
      description: "Number of exosphere nodes."
      label: "Number of Exosphere Nodes:"
      required: true
      default: 1
      type: "int"

Adding the Catalog to Rancher

Now with all the catalog file structure defined you can add your private git repo to Rancher under the Admin -> Settings tab.

A couple of tweaks you need to make to enable private git repos:

1. Add the username and password of your git user in the git url: https://username:password@bitbucket.org/org/catalogs.git

2. Bind-mount ssh keys for your git repo in the rancher server container. This approach will work after v056 is released since currently the server container doesn't come with with the openssh binaries installed

Ideally you would be able to configure git users similar to how Jenkins git plugins do it but is not supported at the time.

Viewing the Catalog

The rancher catalog service has a mechanism that polls periodically the git repo for new changes to keep the catalogs up to date. So right after adding the git repo to Rancher you should see your catalog listed under the Applications -> Catalogs menu

Launching the Catalog

Now you should be able to launch your application catalog and get a running stack with your micro services