Rancher and Rancher Compose documentation is available in the Rancher Docs. But I will explain the basics in this post.
Rancher
The Rancher command-line tool is a tool to manage the Rancher server from your command-line-interface. You can manage environments, hosts, stacks, services and containers.
Before you can use the Rancher CLI tool, you have to create an environment API key in the rancher web interface. Then you have to define the Rancher URL, access key and secret key in environment variables (recommended).
$ export RANCHER_URL=<http://your-ip:8080>
$ export RANCHER_ACCESS_KEY=<access key>
$ export RANCHER_SECRET_KEY=<secret key>
If you don't want to set environment variables, you can also provide the API key, secret and rancher server URL via options.
$ rancher --url <http://your-ip:8080> --access-key <access key> --secret-key <secret key>
Now you're ready to use the Rancher CLI tool. To list all containers run:
$ rancher ps
Rancher Compose
Rancher Compose is a multi-host version of Docker Compose and will upload your docker-compose.yml and rancher-compose.yml to the Rancher server to deploy a new stack with the given configuration. This tool is ideal for CD pipelines!
The Rancher Compose CLI tool works the same as Docker Compose, but before you can use it, you have to authenticate with the Rancher Server. This works exactly the same as the Rancher CLI tool, using environment variables or options.
$ export RANCHER_URL=<http://your-ip:8080>
$ export RANCHER_ACCESS_KEY=<access key>
$ export RANCHER_SECRET_KEY=<secret key>
$ rancher-compose --url <http://your-ip:8080> --access-key <access key> --secret-key <secret key>
Create a docker-compose.yml configuration to test the rancher-compose CLI tool and boot up a new stack.
# -p custom stack name
# -d non-blocking
# -c confirm the upgrade
# --pull pull latest images
# --force-upgrade always try to upgrade containers
$ rancher-compose -p my-stack-name up -d -c --pull --force-upgrade
Download
You can get the latest Rancher and Rancher Compose command-line tools from the Github pages. Because these tools get updated periodically, I created a small bash script to download the two tools and copy them to the /usr/local/bin directory.
Copy the contents below to a bash file and use it to upgrade your rancher CLI and rancher-compose CLI tool periodically.
#!/bin/bash
# Download rancher and rancher-compose command line tools
wget -O rancher-cli.tar.gz $(curl -s https://api.github.com/repos/rancher/cli/releases/latest | grep browser_download_url | grep 'linux-amd64' | head -n 1 | cut -d '"' -f 4)
wget -O rancher-compose.tar.gz $(curl -s https://api.github.com/repos/rancher/rancher-compose/releases/latest | grep browser_download_url | grep 'linux-amd64' | head -n 1 | cut -d '"' -f 4)
# extract the binaries from the tar archive
sudo tar -xzvf rancher-cli.tar.gz -C /usr/local/bin --strip-components=2
sudo tar -xzvf rancher-compose.tar.gz -C /usr/local/bin --strip-components=2
# Remove the archive
rm rancher-cli.tar.gz rancher-compose.tar.gz -f
If you found this post useful, or if you have any questions, leave a comment!