This page describes the steps to launch a new Docker Canary. If you're still reading up, we've got documentation on the Docker Canary background, and how to customise Docker birds.

We strongly recommend that you enable Auto Commissioning on your Flock before following the process below.

I've launched my Canary but can't access it's services! For a note on port-mapping click here.

Step 1: Confirm that Docker Canaries are enabled for your account

Browse to your Console, click the "+" on the top right of the Flock card, then click "Add Canary":

The Docker panel say "X container licenses left", and on putting your cursor on the panel you'll see "Add Docker Canary":

If you don't see this panel, it means Docker birds aren't yet enabled. Please contact Support.

Step 2: Get Docker launch configuration information

Click the "Add Docker Canary" button and you'll see a list of supported Docker images:

Select the version you wish to run, and click "Launch" on the version. This will take you to the configuration retrieval view:

The first tab shows a Kubernetes configuration file, the second tab shows commands to run your Docker Canary directly with the Docker CLI, and the final tab shows the container image repository and retrieval information.

Note: the generated configurations do not use tags to identify Docker containers, but instead use the recommended practice of image digests. This is to guarantee that the same image is always launched, regardless of tags that can change.

Select the route you wish to take (Kubernetes, Docker CLI, or manually configure the container orchestrator).

Step 3a: Kubernetes configuration

If you want to run your Docker birds on Kubernetes, we provide a simple sample configuration. It contains a secret (your credentials for pulling our Docker image), and a simple Pod configuration. However, it does not include ReplicaSets, StatefulSets or any other Kubernetes fanciness. That will be extremely specific to the way you wish to deploy, and the features of your Kubernetes cluster. We expect that the configuration generated for you is a starting point, and will require further customisation. See the Docker customisation page for more information on how to change the behaviour of the image.

Step 3b: Docker CLI

The commands displayed on the Docker CLI tab work well for testing our Docker birds, but aren't expected to be used for production Canaries. You'll quickly get a Docker bird running, but if that container dies there's no orchestration to launch another one.

Step 4: Commission your bird

Note: We strongly recommend that you enable Auto Commissioning on your Console. Without Auto Commissioning, when your container orchestrator relaunches your Docker birds in the future, they will no longer be accepted by your Console until you manually intervene. Ain't nobody got time for that.

If Auto Commissioning is NOT enabled with your Docker bird, then as a final step you'll need to commission the new bird. The means in the Console, you'll see a commission popup, and you'll select the appropriate Flock for the newly launched Docker bird.

The Auto Commission setting affects the Kubernetes configuration we generate for you; if the setting is enabled, it won't have any impact on containers already launched. You'll need to follow the above steps again to retrieve a newly generated configuration.

Docker CLI Port-Mapping

Docker CLI defaults to not exposing any ports on your containers, this means that even if a Canary is configured with a personality, it's services won't be reachable externally. Docker documents this here.

Depending on your chosen services, you'll need to map ports from your Docker host, to your Canary container.

In the below example, we have Canary that was launched with the following command :

sudo docker run -ti --rm -e LISTEN_DOMAIN=ABC123.cnr.io -e CONSOLE_PUBLIC_KEY=ABC123 -e AUTOCOMMISSION_TOKEN=ABC123 thinkstcanary/dockercanary@sha256:ABC123

Then configured with the "Standard Linux Server" personality.

Trying to telnet to the host however fails...

$ telnet 192.168.1.38
Trying 192.168.1.38...
telnet: connect to address 192.168.1.38: Connection refused
telnet: Unable to connect to remote host

Lets redeploy the Canary and map the host port 23 to the containers port 23:

sudo docker run -ti --rm -p 23:23 -e INITIAL_PROFILE=linux-std -e LISTEN_DOMAIN=ABC123.cnr.io -e CONSOLE_PUBLIC_KEY=ABC123 -e AUTOCOMMISSION_TOKEN=ABC123 thinkstcanary/dockercanary@sha256:ABC123

sudo docker run -ti --rm -p 23:23 -p 80:80 -p 443:443

$ telnet 192.168.1.38
Trying 192.168.1.38...
Connected to Dockerhost.localdomain.
Escape character is '^]'.
Ubuntu 14.04 LTS
login: