Building the Release Definition

The Release definition in VSTS allows you to define the steps needed to be taken to deploy a build of your application to your deployment environments. On the Releases tab of your project you click on the ‘New Definition’ button and then select the ‘Empty’ profile. On the next screen it will automatically fill in your current VSTS project and the VSTS build definition so you can just go ahead and click Create.


First things first is rename the autogenerated definition name in to something a little easier to work with. I’m going with the same name as my build definition to keep them in sync. Then we need to make sure that the release agent is the same one that we used for the build process. Click on the ‘Run On Agent’ section and then make sure you set the agent queue to be ‘Default’ and add in a demand of RANCHER_CLI exists.


The script that I use has a set of variables that need to be passed in to it, some variables are unique to the environment and some are available to the entire release definition. To setup the common variables you go to the Variables section and fill in the following with your details. ( Note : the value for DOCKER_HOST should actually read and not as in the screenshot )


Next we come to the environment. The first thing I do is click on the environment name and rename it to reflect the environment that it is for. In this case I’m working on the environment for the development system so I rename it Development. Once renamed click on the three dots in the upper right of teh environment box and select the option to edit the environment variables.


Fill in your Rancher API endpoint and Rancher API keys for this environment and then also add in the Service ID for the dummy service that you setup in the previous blog post and then click OK to close the dialog box.

All that is left now is to add the deployment script which I’ll do in the next post.

Posted in None

Creating A Dummy Service In Rancher

The last thing that we need to do before we can create the deployment scripts is to create a dummy service in Rancher that we can then replace with our deployed application. We need to do this because our deployment scripts need to reference a service id and will fail if the id doesn’t exist yet.

In the Rancher interface create a new ‘Stack’ for your applications. Stacks are a way to organize different applications together.


Give your stack a name and click on the create button. You will end up with  empty stack with no services running. In Rancher a service is one or more containers running a single docker image. Click on the Add Service button.


Give your service a name ( single word lowercase is the best practice ) and then for the Select Image section enter in ‘busybox’. This is just a very small linux distribution that does an excellent job as a temporary standin for our deployment scripts


I am also adding a single environment variable called and setting the value to dev. In your other environments I would set the value to ‘test’ and ‘prod’ as needed. This is used to select to correct spring profile at a later stage in the process.

Click on create button and then when the service has been created click on the service name and take a look at the URL in your browser.


In the URL there are three IDs. The first is the environment ID, the next is the Stack ID and the last one is the Service ID. You will need to take a note of the last one for the deployment scripts.

We are now ready to create the deployment definition in VSTS.

Tagged with:
Posted in Domino To Spring

Adding A Dockerfile to the project

Before we can deploy anything to Rancher it needs to be in a docker image so I’ll be asking my VSTS scripts to build a docker image that can then be uploaded to a Docker container/image repository before being deployed to the Rancher server.

To create the Docker image I need a Dockerfile added to the project and I need to also tell my build script to copy it to a location that the release script can access.

First I will create a new folder in my project under src/main called ‘docker’.


To that folder I will add a new file called ‘Dockerfile’. Make sure you get the case right. It is not camel-case and does not have a capital F in the middle of the filename.

In this file I will add what is probably the simplest Dockerfile instructions you have ever seen.


Basically I’m starting with the openJDK Java runtime environment running on Alpine Linux which is a very small distribution of Linux that can run java apps. I then setup my tmp volume, I copy my jar file in to the image, setup what port should be exposed and then tell it how to run the jar file. The resulting image will be about 60Mb plus the size of your jar file.

You will also need to update the build definition so that it will copy the Dockerfile to the artifact store which will be used during the release process. Back in VSTS find your Build definition and open it for editing.


Select the ‘Add Task’ option and select the ‘Copy Files’ task to be added to the build process. Make sure you move it up above the final stage of Publish Artifact and then fill in the source folder and target folder options.

If you haven’t already then make sure you commit the dockerfile to Git and then push the changes to teh VSTS server and run a new build. This will verify that the build process changes have worked.

Tagged with:
Posted in Domino To Spring

Getting Your Rancher API Keys

Before we can start the process of automatically deploying our application to Rancher we need to setup the API access keys that will allow you to use the Rancher Command Line Interface and API.

Load up Rancher and log in as your administrator account and make sure that you are in the correct environment ( you will need to do this process in each environment that you will be deploying to ) and then go to the API menu.

There are two kinds of API keys in Rancher. There are Account Keys and Environment Keys. The environment api keys are under the advanced settings and you will need to click on that to expand the section. You should also take a note of the API Endpoint URL as you will need this later.


Click on the ‘Add Environment API Key’ button and give your new key a name. I’ve called mine VSTS Access. Then click on the Create button.


The new API key will be displayed, it consists of two parts, the access key and the secret key. As noted this is the ONLY time the secret key will ever be displayed so you must take a note of it.

Make sure you do this for all your deployment environments and keep a note of the keys and endpoint urls ( they change per environment also )

Tagged with:
Posted in Domino To Spring

Defining Your VSTS Build

The build definition in VSTS is designed to build and compile your code and then take the resulting build and save them to an artifact store. You can create build definitions for Visual Studio applications, XCode applications, Android applications and, of course, Java applications. In VSTS go to the Build & Release section of your project and then make sure you are on the Builds tab. Click on the New Definition button to get started.

You should see a list of predefined build templates, the one that we are interested in is the Maven template so I’m going to go ahead and select that one as my starting point. The default Maven template should pretty much work as is but I’m going to make a few minor changes so that it will always build on our new VSTS Build Agent.

First lets make sure that we are building the right thing. On the Tasks tab you should see what sources it is building. It should say the name of your repository and the master branch. If not then select the correct branch.

Over on the Triggers tab you should enable the Continuous Integration section. This will make sure that a build is triggered every time new code is pushed to the master branch. You can also setup scheduled builds so if you have some sort of nightly build process you can automate that here.

The Options tab contains the section that we need to specify the build agent. When we started the VSTS Build Agent it was created in the ‘Default’ agent queue so make sure you have selected that as your queue and you have not selected either of the hosted options.

If you have multiple private build agents and not all of them are based on the Rancher VSTS Build Agent then you will need to add a ‘Demand’. When the build is queued it will look for a build agent that meets all the required demands, this is how you can make sure that Visual Studio builds run on windows boxes and XCode builds run on OS X boxes.

The Rancher VSTS Build Agent sets an environment variable of RANCHER_CLI_VERSION so I’m adding a demand to ensure that this exists. I’m not using any specific Rancher features during the build process but I know that the agent has Maven on it so it is a logical choice to use that agent.

I can now save my build definition and run it for the first time. The build process will start on the different stages and your screen will update as each stage completes ( or fails ). Once completed you can select any of the stages on the left side to review the logs for that stage.


Now that we have a successful build we can start the process of deployment.

Tagged with: ,
Posted in Domino To Spring

A VSTS Build Agent For Rancher

By default Visual Studio Team Services provides you with one hosted pipeline and one private pipeline when you are using the free services. You can add additional pipelines at a cost of $15 a month if you need them however a single pipeline should work ok for a small team.

The private pipeline is something that you run on your own infrastructure and Microsoft provides pipeline agents that will run on Windows, OS X and Linux machines. These agents will listen to your VSTS account and accept jobs for running build and releases. For the purposes of the Rancher/Docker infrastructure I am running a private build agent on a Ubuntu Linux box with some additional Rancher API access features added in and I’m also running it on my Rancher Infrastructure.

First we need to add a stack to run our service in. In the development environment click the Add Stack button. I’m going to called mine ‘tools’ and then just create an empty stack.


Next I click on the ‘Add Service’ button.

To save a some time Microsoft already provides their Ubuntu VSTS Agent as a docker image so you can easily use this as your starting image. To save even more time, however, I have built my own personal docker image that is based on the Microsoft image and adds in the Rancher Command Line Interface and an addition Rancher API script that can do a few things that the Rancher CLI currently can’t do.

If you want to look at the DockerFile it is available in my GitHub repository and the image is available on Docker Hub.

Don’t forget to add your VSTS Environment variables to the container before you start it up or it will fail.

Once you have it running you will see it listed in the tools stack

Now we can start getting VSTS to build our application on our private pipeline box.

Tagged with: ,
Posted in Domino To Spring

Extending Your Rancher Environments

In the last post we setup the Rancher server and added our first Rancher Host. One of the nice features of Rancher is that you can setup multiple environments so that you can keep your Development testing system separate from your QA system and separate from the Production system yet keep a single Rancher server orchestrating it all.

Click on the ‘Environment’ tab and select the option to ‘Manage Environments’


The first thing I’m going to do is rename the Default environment to Development by clicking on the ‘Edit’ button.


I will then click on the ‘Add Environment’ Button to create my new environments. I’ll called One Testing and the other Production. In both cases I will leave the Orchestration Type set as Cattle but as you can see Rancher can also manage other types of Orchestration systems making it very powerful.

Once the new environments are created you will notice that they are listed as unhealthy. This is because there are no hosts assigned to those environments yet.

Select one of your new environments and then add a new host just like you did for the first host. Once you have added a host for all your environments they should all say active.

In a real production environment you would probably have multiple hosts per environment depending on your needs for scaling and backup. When you have multiple hosts in a single environment Rancher can look after scaling apps so that you have the same container running on multiple hosts and can also start a container running on a different host if one of the other hosts is down.

Tagged with:
Posted in Domino To Spring