DarksideCookie

Versioning ASP.NET Core HTTP APIs using the Accept header

chris@59north.com — Wed, 25 Jul 2018 20:19:26 +0000

For some reason, I have spent a couple of days thinking about versioning HTTP based APIs. Actually, the reason is that I have a client who is using quite a lot of HTTP based APIs, but in a way that I find less than perfect. I’m not blaming them in any way, as it is the result of growing an application over many years, using many different forms of Microsoft tech, and continuosly focusing on delivering features to users instead of building a maintainable system. Currently their application uses ASP.NET WebForms, ASP.NET Core MVC, asmx webservices, WCF webservices, Silverlight, Angular etc, which is what happens in quite a lot of cases over time.

One of the things that have been bothering me is their use of the HTTP services. Sure, it is a great step up from asmx, and even WCF services, as they have been moving from Silverlight to Angular and JavaScript. Unfortunately, as different developers have worked on different applications in the solution, they have created their own API endpoints to suit their needs. Often endpoints are more or less duplicated just to get the returned entity representation to take a slightly different shape.

A very basic example would be a user endpoint. Sometimes when you retrieve a user, you might only need a very limited subset of information about that user. And in other cases you might want a lot more information. And being developers, we obviously don’t think we should retrieve a bunch of fields regarding a user when we don’t need it. Not to mention that the user retrieving the data might not be allowed to view all the fields. So to solve that, there are a bunch of different “get user” endpoints, each returning a specifically designed representation of the requested user, each used from a specific application, or even a specific part of an application. And this means a lot of duplicated code, as well as a very hard to use API.

API versioning

Even if we don’t need to have several different representation of an entity in our application, there is another situation that is very similar, and that comes up all the time. Versioning… How do we version an API? For example, in version 1, the user entity contained a set of very well defined set of values, including an age field. However, when working through the API for version 2, it was decided that passing a date of birth would be much better, as some apps wanted more control than just an age. So how do we solve this? Well, there are a couple of ways…

In this particular case, one could just add another field to the representation and be done with it. It wouldn’t cause any problems with existing clients, but would offer the new functionality consumers of version 2. ANd this is a great way to extend the API from v1 to v2. However, in some cases this doesn’t work. What if in v1 we return a date of birth, but then realize that that might be a privacy issue and want to replace it with just an age. That would be a breaking change, causing problems for every single application depending on the API.

There are 4 common ways to handle versioning of APIs

1. Modify the path – https://example.com/v1/users/1

Adding the version to the path is simple and easy to do, and easy to consume. The problem with this solution however, is that the path should be stable. This means that the representation of an entity should always be available at the same path. By changing the path, we are kind of saying that it is 2 different entities, whereas it is really just 2 different representations of the same entity.

2. Add a querystring parameter – https://example.com/users/1?version=1

Using a querystring to pass the version is also very nice and easy. However, for me, querystring parameters has to do with querying. And by that I mean that, for me, querystring parameters should be used to filter, or query, the information that is being requested, not to tell it what representation that should be used for the returned data.

3. Add a custom header – version: 1

The third option is to have the client consuming the API pass the version to the server using a custom header. This takes moves the concern from the path to another part of the transport, which is nice. However, it does make it harder to send the request. You can’t easily just type it into the addressbar of you browser and get the response. Instead you need a specific tool to do it. On the other hand, for me, that isn’t a huge problem. APIs are supposed to be consumed by applications (code), not by users using a browser, so it shouldn’t be a big problem. But why would you do it this way, when there is a built in way in the HTTP specification as you will see in the fourth way?

4. Use the Accept header – Accept: application/vnd.myapp.v1.user+json

HTTP already defines a header to this problem. It is the Accept header. It is used to tell the server what types of response that the client can accept. Often this header is used to request JSON by passing the value application/json, or html by passing the value text/html. However, the spec defines the value as a string. So you can literally pass along any form of string value that you want. But there are some nice conventions that you might want to follow. First of all, it is generally a 2 part value, split by a /. The first part gives a high-level type like “text” or “image” for example, and the second part defines it more spcifically like “text/html” or “image/png”. But as I said, any string is valid, so the xxx/yyy is just a convention, it isn’t in any way enforced. For formats that are consumed by applications, like JSON for example, the first part is often “application”. And for custom formats used by specific APIs, the convention is to prefix the 2nd part with “vnd.” to indicate that it is vendor specific. After that, you put the definition of what you are requesting. In this case I chose “myapp.v1.user” to indicate that the representation that I want should be a “user” from the “myapp” application, and that I want version 1. But once again, you can format this in any way you want.

However, using the accept header to indicate a custom representation causes a problem. Normally, this header is used to define what serialization format should be used, such as JSON or XML. Replacing this with a custom string means that we need to find another way to convey that information. The common way to do this, is to append it to the string, separating it with a + sign. In this case I added “+json” to indicate that I want my “application/vnd.myapp.v1.user” representation sent to me using JSON. I could have added “+xml” to get it in XML format if my backend supported this.

API versioning thoughts

All of the above mentiond ways work for versioning APIs. They each have benefits and downsides, and I don’t think any of them are “the right way”. It all depends on you requirements, as so much does in our line of business. But my personal preference is option 4, using the Accept header. Mostly because it uses a predefined feature in HTTP, and following standards makes things a lot easier in most cases. I’m sure that the people who designed HTTP are MUCH smarter than me, and have thought of WAY more scenarios than I have. So I’ll trust those guys, and try to follow their recommendation. However, if it is a requirement that you should be able to call the API from a browser, well, then I guess I would have to choose option 1 or 2. Option 3 is probably my least favorite, but on the other hand it has some benefits. By using the Accept header to pass the format to be used, JSON or XML for example, I can used the built in content negotiation in the ASP.NET Core framework to solve the formatting, and just look at the custom header to figure out the representation to use. So they all have their place in one form or another.

Using the Accept header versioning in ASP.NET Core MVC routing

ASP.NET Core MVC routes requests to actions using either convention based routing with templates, or using attributes. Personally I prefer the attributes when building APIs, as it gives me better control over the paths being used, and also makes it easier to understand the path by looking at the controller and the attributes.

However, the built in stuff doesn’t take any headers into account. The Accept header is only taken into account when formatting the returned value. So to make use of that header while routing, we need to write some code, but luckily it is not very complicated code.

What we need is an implementation of IActionConstraint. This is an interface that is used to programmatically add a constraint to an action, basically allowing us to use logic to tell the routing engine whether or not an action can be used to handle the current request. Using this, we can add an attribute to an action, and define what accept header value should be passed for this specific action to be executed.

The IActionConstraint interface has 2 members that needs to be implemented

bool Accept(ActionConstraintContext context)
int Order { get; }

The Accept method gets a “context” with information regarding the current request, and returns a boolean defining whether or not this request can be used to handle this request. And the Order property defines in what order the action’s costraints should be executed. The lower the number, the earlier in the list it will be executed.

There are a couple of ways to go about building the IActionConstraint that we want. We could create a class that inherits from Attribute, and implements IActionConstraint. Or, we could go and create a class that inherits from ActionMethodSelectorAttribute, and implement the IsValidForRequest method. And being me, I’ll go for the simplest solution, and just create a class called AcceptHeaderAttribute and inherit from ActionMethodSelectorAttribute.

public class AcceptHeaderAttribute : ActionMethodSelectorAttribute {
public override bool IsValidForRequest(RouteContext routeContext, ActionDescriptor action) { … }
}

Next, I need to know what Accept header value it should check for. So I add a constructor that accepts a string defining this

public class AcceptHeaderAttribute : ActionMethodSelectorAttribute {
    private readonly string _acceptType;
    public AcceptHeaderAttribute(string acceptType)
    {
        this._acceptType = acceptType;
    }
   …
}

Now that I know what Accept header value should be passed, I can implement the IsValidForRequest method

public override bool IsValidForRequest(RouteContext routeContext, ActionDescriptor action)
{
     var accept = routeContext.HttpContext.Request.Headers.ContainsKey("Accept") ? routeContext.HttpContext.Request.Headers["Accept"].ToString() : null;
     if (accept == null) return false;

    var acceptWithoutFormat = accept;
     if (accept.Contains("+"))
     {
         acceptWithoutFormat = accept.Substring(0, accept.IndexOf("+"));
     }

    return acceptWithoutFormat == _acceptType;
}

I start out by checking to see whether or not there is an Accept header at all in the request by looking at the RouteContext’s HttpContext. If there isn’t an Accept header I return false, as without the header this action is not an option for execution.

Next I remove any potential formatting information from the header by removing anything after a +-sign, including the potential +-sign.

And finally, I just return whether or not the remaining string corresponds to the configured value.

That’s all there is to it! And using it is just as simple. Just add it to an action like this

[HttpGet("{id:int}")]
[AcceptHeader("application/vnd.mydemo.v1.user")]
public async Task<IActionResult> GetUserById(int id)
{
     var user = await _users.WhereIdIs(id);
     if (user != null)
         return Ok(user.ToModel());
     return NotFound();
}

[HttpGet("{id:int}")]
[AcceptHeader("application/vnd.mydemo.v2:user")]
public async Task<IActionResult> GetUserByV2(int id)
{
     var user = await _users.WhereIdIs(id);
     if (user != null)
         return Ok(user.ToModelV2());
     return NotFound();
}

Another nice feature is that you can easily handle the case where an Accept header is not passed at all, by adding

[HttpGet("{id:int}")]
public IActionResult GetUserByIdDefault(int id)
{
return StatusCode(406, "Invalid Accept header");
}

As you can see, it has the same HttpGet attribute as the other actions, but no AcceptHeader attribute. This means that when the router looks at the actions, it will select the one without the AcceptHeader attribute if it’s missing. This means that the client gets an HTTP 406 back if the header is missing. You could obviously also have the “bare” action be v1, and default to that for any request missing the header or with an invalid header if you wanted to. On the other hand, that might be a little confusing to someone who wanted v2 but forgot to pass the Accept header, or passed an incorrect value. But if you have an API that currently doesn’t use this kind of versioning, it might be a great way to move forward with it without breaking existing clients.

Customizing the ASP.NET Core MVC content negotiation to handle custom Accept headers

There is a small problem with the current solution. If you want to support content negotiation, and multiple response formats, ASP.NET Core MVC can easily to add other formats than the default JSON formatter by adding other output formatters. This is done when configuring the MVC services like this

services.AddMvc(config => {
config.OutputFormatters.Add(new XmlSerializerOutputFormatter());
});

However, the content negotiation built into ASP.NET Core MVC uses the Accept header to do it’s work. So when we stop using “application/json” and “text/xml”, it breaks down. So to sort this out, we either need to create our own custom IOutputFormatter implementations, or modify the way that the formatter is selected. I’m going to go for the latter in a slightly hacky, but working way.

I don’t feel like doing too much work, and I believe that what is already in the framework works very well, so all I want to do is hack in a little change using a custom OutputFormatterSelector that makes the new Accept header format work with the existing implementation.

For this, I’ll go ahead and add a new class called AcceptHeaderOutputFormatterSelector, and have it inherit OutputFormatterSelector.

public class AcceptHeaderOutputFormatterSelector : OutputFormatterSelector {
}

And since I like the default implmentation from the framework, I’ll add a constructor that sets up an instance of that OutputFormatterSelector internally in my class

public AcceptHeaderOutputFormatterSelector(IOptions<MvcOptions> options, ILoggerFactory loggerFactory, string defaultContentType = "application/json")
{
     _fallbackSelector = new DefaultOutputFormatterSelector(options, loggerFactory);
     _formatters = new List<IOutputFormatter>(options.Value.OutputFormatters);
     _defaultContentType = defaultContentType;
}

As you can see, it accepts some MvcOptions, an ILoggerFactory and a string containing the default format to use, which I default to application/json. And then I use those values to create a new instance of DefaultOutputFormatterSelector, which is the implementation used by the framework by default. The values are then stored globally so that I can use them later in my class.

The OutputFormatterSelector class is abstract, and requires you to implement the SelectFormatter method. It looks like this

public IOutputFormatter SelectFormatter(OutputFormatterCanWriteContext context, IList<IOutputFormatter> formatters, MediaTypeCollection mediaTypes);

This is the method that is called by the framework to figure out what output formatter to use when serializing the response. It gets a “context” with all the essential information, a list of formatters to use, which should override the list of formatters passed into the constructor, and a collection of media types.

So how do I implement this. Well, I want a version that, if the Accept header contains a custom content type with a “+[format]” definition, replaces the custom content type with a standard one, and then let’s the default implmentation of the selector figure out the rest.

To do this, I implement the method like this

public override IOutputFormatter SelectFormatter(OutputFormatterCanWriteContext context, IList<IOutputFormatter> formatters, MediaTypeCollection mediaTypes)
{
     if (!HasVendorSpecificAcceptHeader(context.HttpContext.Request))
         return _fallbackSelector.SelectFormatter(context, formatters, mediaTypes);

    if (formatters.Count == 0)
     {
         formatters = _formatters;
     }

    context.ContentType = GetContentTypeFromAcceptHeader(context.HttpContext.Request);

    var formatter = formatters.FirstOrDefault(x => x.CanWriteResult(context));

    context.ContentType = context.HttpContext.Request.Headers["Accept"].First();

    return formatter;
}

First, I verify that the request has a vendor specific content type. This basically just means that I check if the Accept header value starts with “application/vnd.”

private bool HasVendorSpecificAcceptHeader(HttpRequest request)
{
return request.Headers["Accept"].First().IndexOf("application/vnd.") == 0;
}

If it doesn’t have a vendor specific value, it just uses the default implementation to do the work. If it does on the other hand I carry on by checking to see if the passed in list of formatters is empty, in which case I use the default once that I received in the constructor instead.

Once I have my list of formatters, I get the “proper” content type by calling a helper method that looks like this

private string GetContentTypeFromAcceptHeader(HttpRequest request)
{
     var acceptHeaderValue = request.Headers["Accept"].First();
     if (acceptHeaderValue.IndexOf("+") > 0)
     {
         var contentType = acceptHeaderValue.Substring(acceptHeaderValue.IndexOf("+") + 1);
         if (_contentTypeMap.ContainsKey(contentType))
             return _contentTypeMap[contentType];
     }
     return _defaultContentType;
}

It pulls out the Accept header and looks to see if it contains a +-sign. If it doesn’t, it returns the default content type fromt he constructor. But if it does, it takes the part of the string after the +-sign, eg json or xml, and passes that to a dictionary that will map those values to proper types like application/json or text/xml. If there is no conversion available in the map, it just fallbacks to the default type.

Once I have the “proper” type that the framework knows about, I set the context’s ContentType property to this value, before iterating through all the formatters to see which formatter can write a result for this value. Once I have my formatter, I reset the context’s ContentType to the value of the Accept header to make sure that the response to the client has the Content-Type header set to the same type that has been requested. If I don’t do this, the client will request one type, but get a generic application/json Content-Type back.

Once I have my AcceptHeaderOutputFormatterSelector implemented, I can add the XmlSerializerOutputFormatter and replace the default format selector in the ConfigureServices method in the Startup class like this

services.AddMvc(config => {
config.RespectBrowserAcceptHeader = true;
config.OutputFormatters.Add(new XmlSerializerOutputFormatter());
});
services.AddSingleton<OutputFormatterSelector, AcceptHeaderOutputFormatterSelector>();

Note: ASP.NET Core MVC defaults to JSON and ignores the Accept header by default. So to enable content negotiation based on the Accept header, you need to set the RespectBrowserAcceptHeader property on the MvcOptions.

That’s “all” there is to it to get this to work… Yes, it it not real production quality code, but it works and could be extended to production quality with some testing and so on. But for now, all I wanted, and needed, was a prrof of concept that it works, and it does!

If you want to see some code, I have uploaded some sample code to my GitHub account, which you can find here: https://github.com/ChrisKlug/AspNetCoreMvcAcceptHeaderRouting

Hope this helps in some way, or at least gave you some ideas of how to solve some problem that you have, or might run into in the future!

Using Azure Files with Azure Container Services and Docker volumes

chris@59north.com — Mon, 23 Oct 2017 16:45:35 +0000

As a continuation to my last post about setting up an Azure Container Service, I thought it might be a good idea to have a look at persistent storage for the containers. Even if I prefer “outsourcing” my storage to external services, having persistent storage can be really useful in some cases.

Docker sets up storage using volumes, which are bascially just some form of storage that is mounted to a path in the container. By default, the volumes are just directories on the host that are mounted inside the container. However, this has a couple of drawbacks.

If the container is taken down and set up on a new host, the data in the volume will be gone. Or rather, it will still be there, but on another host. So, in the eyes of the container, it's gone. The only way to make sure that the data is persisted properly, is by setting up affinity between the service and the host. But this is a REALLY crappy solution. It breaks the idea that a container should preferably be able to run on any agent in the cluster.

On top of that, if a host is replaced, the data dissappears. And in a cluster where machines should be cattle, and load should be handled by expanding and contracting the cluster, hosts come and go. So tieing the storage to a specific host is just not a good idea.

The solution is to map our volumes to something else than the host, and in the case of Azure, that would preferrably be Azure Storage. And the way this is done, is by setting up an Azure File in storage, and map that as a volume using SMB.

But wait...this sounds really complicated! Is this really the only way? Can't I just click some buttons and have it done for me? Well...no, yes, no. It isn't that complicated to be honest. But yes, there are a few steps involved, but they are all pretty basic. And yes, you currently have to set it up manually. There is no button you can click in the Azure portal to get it up and running unfortunately. Not yet at least.

So, without a button in the Portal, how do we go about doing it?

Step 1 - Creating a Docker Swarm and Storage Account

The first step is to set up a new Docker Swarm in Azure. Luckily this is a piece of cake to do using the Azure Portal, and the Azure Container Service. If you haven't done that before, I suggest having a look at my previous post. It covers how you set up a swarm, and what Azure actually provisions for you when you do it.

In my case, I created a Docker Swarm with a single master and a single agent. There is no need for a bigger cluster to test this. More nodes, just mean that you have to repeat the set up process for the driver more times.

Besides the Container Service, we will need a storage account. So go ahead and set that up as well while you wait for the ACS to provision all of its resources.

Step 2 - Connect to the Swarm

Once the swarm is up an running, you need to connect to the swarm master using SSH. Once again, this is sort of covered in the previous post, but in that post, I showed how to set up a tunnel and have the Docker client working against the master. In this case, I want to connect straight to the master, and execute commands on it. So to do that, I opened a terminal and executed

ssh -p 2200 zerokoll@chrisacstestmgmt.westeurope.cloudapp.azure.com

This connects to a Azure Container Service called chrisacstest using a user called zerokoll. If your service isn't called chrisacstest, it will look like this

ssh -p 2200 [USERNAME]@[CONTAINER SERVICE NAME]mgmt.[AZURE REGION].cloudapp.azure.com

It might also be worth noting that I use port 2200 instead of the SSH default 22. Port 2200 is then forwarded to 22 by the load balancer...

Once connected, you can run

docker info

to see what the current state of the Docker Swarm is.

At least you might think so... However, you might note that this doesn't give you the response you would have expected. It contains no information about a swarm...but there is a good reason for this. You are currently connected to the master host. Running docker info gives you the information about the Docker set up on this node. And this machine isn't part of a swarm.

Wait...what!? What do I mean that the master node isn't part of a swarm? Well...it is...but it's not. It runs a Docker container that is configured as a master in the swarm.

So, if you run

docker ps

you can see that the host you are connected to is running a container based on an image called swarm:1.1.0, which is the actual swarm master. That container has port 2375 mapped to the host. So, in the previous post, when we set up the SSH tunnel and bound port 2375 on the host to port 2375 on the local machine, we were actually binding to a port that was in turn is bound to port 2375 on the swarm master container. So we were issuing commands to that container, not the host...

To get the info about the Docker master, we need to run the following command

docker -H 127.0.0.1:2375 info

This tells the Docker client on the host machine to issue its commands against port 2375 on the local machine, which is then bound to the Docker container that we really want to query. So, this should give us some information about the swarm.

Anyhow...let's not go further down that rabbit hole! I just thought that I needed to give that information as it might cause some confusion...

The swarm master host isn’t actually the machine that we will be running containers that use Azure File backed volumes, but I'll go ahead and add the driver here anyway. Mainly because it is easier to see what is being done at this level, than it is another level down in the agents. So I'll start out by setting it up here, just to show how it's done, and then I'll go on and set it up on the agent node.

Step 3 - Setting up the Azure File Volumet Driver

The first step is to get hold of the required volume driver, which is located on GitHub. The available releases are available here. At the time of writing, the latest version is 0.5.1, so I'll be using that... And since we'll be doing things that require root access, I'll go ahead and run

sudo -s

This will start an interactive shell run as root

Note: If you are a Windows user and have very little experience with Linux, like me, you'll note the change in the prompt from [user]@swarm-master-XXXX-0:~# to root@swarm-master-XXXX-0:~#

Next, we want to download the driver and place it in /usr/bin. And to do that, I'll use wget

wget -qO /usr/bin/azurefile-dockervolumedriver https://github.com/Azure/azurefile-dockervolumedriver/releases/download/v0.5.1/azurefile-dockervolumedriver

and since that file needs to be allowed to execute, I'll run chmod and set the access permision to allow it to execute

chmod +x /usr/bin/azurefile-dockervolumedriver

Once the driver is in place, we need to get the upstart init file for it. This is a file used by upstart to start the service.

Note: The master node currently runs Ubuntu 14.04.4, which uses upstart instead of systemd, which is used by later versions. If you are running a later build, the service set up is a little different

The init config file is located on GitHub as well, so all I have to do is call

wget -qO /etc/init/azurefile-dockervolumedriver.conf https://raw.githubusercontent.com/Azure/azurefile-dockervolumedriver/master/contrib/init/upstart/azurefile-dockervolumedriver.conf

The last thing that is required, is to configure the volume driver. We need to tell it what Storage Account and key should be used. To do this, we need to create a file called azurefile-dockervolumedriver at /etc/default. So I'll run the following commands

touch /etc/default/azurefile-dockervolumedriver
echo "AF_ACCOUNT_NAME=chrisacsteststorage" >> /etc/default/azurefile-dockervolumedriver
echo "AF_ACCOUNT_KEY=D+rYUTUC14ALS13gxprCsBJMEu0..." >> /etc/default/azurefile-dockervolumedriver

First I use touch to create the file, and then I just use echo to write the values I want in there. As you can see, I set the AF_ACCOUNT_NAME to the name of my storage account, and the AF_ACCOUNT_KEY to the access key for that account.

Once all of that is in place, I can reload the service configuration to include the new stuff, and then start the Azure File Volume Driver service

initctl reload-configuration
initctl start azurefile-dockervolumedriver

This should output azurefile-dockervolumedriver start/running, process XXX to let youy know that everything has worked as expected.

Now that the service is up and running, we can test the driver by creating a container that writes some data to it.

Step 4 - Testing the driver

The easiest way to verify that everything is working as it should, is to create a volume and write some data to it. And yes, I'm still on the "wrong" host to try this on. This should be done on the agents, but once again, it is just easier to try it here before we move on to the agents.

So let's try running

docker volume create --name my_volume -d azurefile -o share=myshare

to create a new Docker volume called my_volume, using the driver called azurefile, using an Azure File called myshare.

Next I'll go ahead and start an interactive alpine-based container, with the newly created volume mapped to /data/

docker run -it -v my_volume:/data --rm alpine

and inside that container, I'll go ahead and run

touch /data/test.txt
echo "Hello World" >> /data/test.txt
exit

If everything went well, you should now be able to open up the Azure Portal, browse to the Storage Account you are using and click Files and see a new file service called myshare. Inside it, you'll find the file you just created in the container.

Ok, so that's kind of cool, but how does that help us? Well...that is persistent storage. So if we were to map that drive as a volume on the agents, and then use that volume from the containers in the swarm, we should have a great place to store presistent data. So let's try that!

Step 5 - Installing the driver on the agent(s)

Now that we know that it works, we need to set up the driver on each one of the agent nodes. And yes, you need to do it on each one. And yes, if you ever add more agents, you need to set it up on those as well...

Note: This process could probably be simplified quite a bit by using some smart scripts, but I only have a single agent, so I'll just go ahead and do it manually in this case.

The first thing we need to figure out is how we can connect to the agent nodes. They aren't set up to be available over SSH from the internet. However, they are open to connect to over SSH from the master node, so that's what I'll do. But..to be able to do that, we need to have the private key for the SSH. So I'll start out by disconnecting the current connection to the master by running

exit
exit

The first one exits out of the root shell, and the second exits from the SSH connection.

Next I'll run

scp C:\Users\chris\.ssh\id_rsa zerokoll@chrisacstestmgmt.westeurope.cloudapp.azure.com:~/.ssh/id_rsa

This uses secure copy to copy my private key, id_rsa, from my local machine to the master node, placing it in the /.ssh/ directory. I can then use that key when connecting from the master to the agent.

Next, I re-open the SSH connection to the master node

ssh -p 2200 zerokoll@chrisacstestmgmt.westeurope.cloudapp.azure.com

and once I'm connected, I need to set the permissions to the id_rsa file by calling

chmod 600 ~/.ssh/id_rsa

This sets the permissions required to give the owner of the file is read and write access

With that in place, we need to figure out where my agents are located. This can be done by calling

docker -H 127.0.0.1:2375 info | grep -oP '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'

This asks for the swarm master container's information, and then uses grep to get the IP addresses based on a Regex. In my case, I get a single address, 10.0.0.5.

Now that I know where my agent is, I can start setting up the Azure File Volume Driver on it. So I'll go ahead and run

scp /usr/bin/azurefile-dockervolumedriver zerokoll@10.0.0.5:~/
ssh zerokoll@10.0.0.5 sudo mv azurefile-dockervolumedriver /usr/bin/
scp /etc/default/azurefile-dockervolumedriver /etc/init/azurefile-dockervolumedriver.conf zerokoll@10.0.0.5:~/

to copy all the required files to the agent node. Unfortunately 2 of the files are named the same, so I have to start out by copying the driver and moving that to the correct location, before copying the rest of the files. I can then connect to the agent and run the following commands

ssh zerokoll@10.0.0.5
sudo -s
mv azurefile-dockervolumedriver.conf /etc/init/
mv azurefile-dockervolumedriver /etc/default/
chmod +x /usr/bin/azurefile-dockervolumedriver
initctl reload-configuration
initctl start azurefile-dockervolumedriver
exit

As you can see, I start out by connecting to the agent node using SSH. Then I elevate my priviledges to root before moving the config and init files to their final locations, and setting execute permission to the driver executable. Finally I reload the configuration and start the azurefile-dockervolumedriver service before exiting the elevated shell.

Now that the driver is up and running, we can verify that the driver works by running

docker volume create --name my_volume -d azurefile -o share=myshare

to create a volume connected to the Azure File we used earlier, and then

docker run -it -v my_volume:/data --rm alpine

to start a new interactive alpine-based container. Once inside the container, we can run

cat data/test.txt

If everything works as it should, this should output "Hello World". The content we put into that file when we tried out the driver from the master host.

From here, you should now be able to deploy containers to the cluster, using the Azure File Volume driver to connect the volumes to persistent storage. Just remember to repeat the process for all the agents if you have more than one. Otherwise you will get issues when you try running a container on a host that doesn't have the Azure File Volume driver installed and configured.

That's pretty much it for this time! The whole set up is a bit convoluted, and could probably be simplified a bitusing some smart scripts, but as a demo of how it works, I think this works...

A brief look at Azure Container Service

chris@59north.com — Fri, 20 Oct 2017 14:57:30 +0000

Yesterday I had a couple of hours left over as I was on a train on the way to do a presentation. So I thought i would play around a little with the Azure Container Service. Seeing that I have gotten hooked on Docker, having the ability to spin up a Docker cluster while on the train using just my mobile phone for the connection, seems like a really cool thing. I guess normal people read books and watch Netflix on the train. Me...I spin up 5 Docker clusters...

Setting up an Azure Container Service is really simple, so let's have a look at it.

Setting up a new Container Service

You just go to the portal and choose to add a new Azure Container Service, and accept that it will use the Resource Manager deployment model. Then you have to fill out a bit of information.

First you have to fill out some basic information. It wants a name for the service, the subscruption that should pay for it, a resource group to place it in and a region to put it in. Pretty basic stuff.

Next it wants to know what kind of orchestrator you want to use, and how you want to set up the masters in the cluster. In my case, I chose Docker Swarm for the orchestrator. Then you need to give it a unique DNS name prefix. It needs to be unique as it will be used as a prefix for the 2 domain names that are set up for your cluster. Once you have defined that, you need to tell it what username should be used for the admin account for the machines, as well as the SSH public key to use when connecting to it. And finally, you have o tell it how many masters you want. You get the option of 1, 3 or 5, which are all automatically distributed among fault and update domains to make sure that they don't all go down at the same time. It would be kind of useless to have multiple masters, if they all go down when something goes wrong, or they are updated...

But before I go any futher, I want to go out on a tangent and talk about SSH keys...

SSH keys

A lot of developers work with SSH keys and SSH connections all the time, but not all of us. To be perfectly honest, this is actually one of the first times ever that I have had to create SSH keys. It all depends on the environment you work in.

So what are they, and what do we need them for? Well, it is actually not that hard. It is just a private/public key pair that is used to securely communicate between 2 endpoints. When you connect to a master in the cluster, you do that by setting up an SSH tunnel. This is a secure connection between your machine and the server, where your machine encrypts the data with the private key, and the server uses the public key that you just provided in the portal.

If you haven't created a set of SSH keys before, I thought I would quickly mention how to do that. It is really simple. All you have to do is run the following command in the terminal

ssh-keygen -t rsa -b 4096 -C "[YOUR E-MAIL ADDRESS]"

This will then ask you where to put the generated files. I just accepted the default, which is C:\Users\[USERNAME]\.ssh\. And then it wants you to input a passphrase to make sure that you are the only one that can use the keys.

Once the command has completed, you will have a brand new set of SSH keys!

However, if you are on a Windows machine, like me, you probably get an error saying that it can't find the executable ssh-keygen. So where do yougo to get that? Well, if you have Git installed on your machine, you are in luck. That installation actually gives you that executable, as well as a few other ones, as part of the package. All you have to do is to add the path %Program Files%\Git\usr\bin to your path, and you are good to go.

Once you have the keys generated, you can just open the file called id_rsa.pub in Notepad, and copy the key.

Ok, after that side note, let's get back to creating the cluster!

More configuration

As soon as we have set up the master node configuration, we need to configure the agents. However, this is a lot easier than the rest of the config. You just need to set up how many agents you want, and what size of machines you want to use. In other words, how much load do you need to handle, and how big is your wallet.

That's it! As soon as the portal has verified the values, you can click OK, and get your cluster set up! It takes a bit of time though... On the other hand, once you see what it has set up, you will understand why. There are quite a few pieces involved in setting up the cluster. And that is actually part of the reason I wanted to write this post. I wanted to have a better look at what is actually being created. Since everything is created automatically, the pieces are named less than perfect, and since there as so much stuff being created, it can be hard to figure out how it all fits together.

When the creation is done, you get all your new services added to the resource group you chose. So what is actually being created? Well, let's walk through it and have a look!

What do you get?

I'll go outside in, from the internet to the machines, instead of by name or service, as I think that makes it easier to understand how the different parts fit together.

First of all, we get a Container Service with the name we set up. This service in itself is pretty boring, and doesn't give us a whole lot of information.

"Inside" that, we get a Virtual Network (swarm-vnet-XXX) that connects all of the VMs in the cluster. Actually, it connects to the network interfaces connected to the master VMs and to a Virtual Machine Scales Set containing the agents. But for simplicity, let's just say that it connects the machines in the cluster... The virtual network is set up with 2 address spaces, 10.0.0.0/8 and 172.16.0.0/24. The 2 address spaces are used by 2 subnets, swarm-subnetMaster (172.16.0.0) and swarm-subnet (10.0.0.0).

Seeing that the network is split into 2 parts, one for the masters and one for the agents, I'll look at the cluster based on that. I'll start out by looking at the master side of things...

On the swarm-masterSubnet subnet, there is a Load Balancer (swarm-master-lb-XXX) that manages the masters. It adds NAT, mapping TCP port 22 and 2200 to port 22 on the master.

And what is port 22? Well, it's SSH. So this NAT allows us to connect to the master using SSH.

And if you have more than one master, it maps port 220x to port 22 on each of the masters, where x is a sequential number that gives us port 2200, 2201 and 2202 in a 3 master cluster. This makes it possible to connect to each one of the masters by choosing the correct port to use.

The Load Balancer connect to the master machines using one or more Network Interfaces (swarm-master-XXX-nic-x). So depending on the number of masters you choose, you will have one or more Network Interfaces defined.

Each one of the potentially multiple Network Interfaces are then connected to a Virtual Machine (swarm-master-XXX-x) that plays the role of Swarm Master in the cluster.

And that is pretty much it for the master side of ot the network. However, there are 2 more things that is set up for us.

First of all, all the masters are connected to an Availibility Set (swarm-master-availabilitySet-XXX). This availibility set is responsible for spreading out the the masters across fault and update domains, to make sure that they don't all go down together if something happens.

And secondly, there is a Public IP Address (swarm-master-ip-[ACS SERVICE NAME]mgmt-XXX). This is a public IP address that is connected to the Load Balancer, giving us a public endpoint that we can use to reach our master nodes. It also happens to be configured with a DNS name, which is defined as [ACS SERVICE NAME]mgmt.[REGION].cloudapp.azure.com. So whenever we want to connect to our Swarm masters, we can connect to that address.

Ok, so that takes care of the master end of things. But what's the situation on the agent side of things? Well, a lot of it is very similar...

On the swarm-subnet, there is another Load Balancer (swarm-agent-lb-XXX) that manages the incoming requests, and fowards them to the agents. However, this Load Balancer actually does sort of load balance the incoming traffic instead of just forward ports to machines. It has load balancing set up for port 80, 443 and 8080, passing the requests to something called Backend pools. These "pool" of machines, are sets of machines that should handle the incoming requests. In this case, there is a single pool (swarm-agent-pool-XXX), containing...no not a set of agents…but a Virtual Machine Scale Set.

So the Load Balancer forwards the incoming requests to a Virtual Machine Scale Set (swarm-agent-XXX-vmss). This is a uniform set of machines that are handled together as a "unit". The set can then be scaled out and in, and Azure takes care of setting everything up for us. So all we have to do, is to tell it what OS, machine size and count we want, and Azure takes care of the rest. It even makes sure to spread out the machines across fault and update domains and so on, to make sure it is as highly available as possible.

And finally, we get a bunch of Storage Accounts to hold the OS disks and diagnostics data.

So that's pretty much what we get when we set up a new Azure Container Service! It is quite a few pieces that has to be set up, and work together for everything to work. So it’s kind of nice that Azure sorts that all out once we have defined the basic requirements! But how do we go about starting up a container in the cluster we just created? Well...that isn't that hard!

Connecting to the master a.k.a Getting your SSH on

The first thing we need to do, is to set up an SSH tunnel to the Swarm Master. This isn't complicated as such, but for me as a Windows person, it feels a bit awkward. But just relax and let go of that! It’s not hard, and it is pretty cool once you have tried it. Just open a terminal and run the following command

ssh -fNL 2375:localhost:2375 -p 2200 [ADMIN ACCOUNT]@[CONTAINER SERVICE NAME]mgmt.northeurope.cloudapp.azure.com

This opens up an SSH tunnel from your machine to the Swarm manager in the cloud. It connects to the manager using port 2200, encrypting the traffic using the SSH keys. It then maps port 2375 on your local machine to port 2375 on the remote machine. So anything you send to localhost:2375 will be sent to port 2375 on the the remote machine, tunneled securely using SSH. The endpoint [ADMIN ACCOUNT]@[CONTAINER SERVICE NAME]mgmt.northeurope.cloudapp.azure.com just says that you want to connect to [CONTAINER SERVICE NAME]mgmt.northeurope.cloudapp.azure.com, using the account [ADMIN ACCOUNT].

Actually, that is what happens if you just pass in -L. The -fN is to connect the current terminal to the tunnel, allowing us to use the terminal to communicate with the master.

Once the tunnel is up and running, we need to tell our Docker client that we want to communicate with our Docker master in the cloud using that port. So, to do that, we need to set the DOCKER_HOST environment variable, which is easily done by calling

set DOCKER_HOST=:2375

if you are using CMD, or

export DOCKER_HOST=:2375

if you are in Bash.

And if you want to verify that you are connected, you can just try running

docker info

to see if you get a response.

Starting your first container

Once you are connected, you can run a new container like you would in any other scenario... For example, I ran

docker run -d -p 80:80 --name demo_app zerokoll/demoapp

which started a very simple ASP.NET Core container that I had uploaded to my own Docker Hub repo. And as you can see, I mapped the external port 80 to the containers port 80. This is possible because port 80 is mapped in the agent load balancer by default. Together with port 443 and 8080. But, if you want to use any other ports, you need to remember to map those ports through the balancer.

Once the container has started, you can just browse to the agent endpoint ([CONTAINER SERVICE NAME]agents.[REGION].cloudapp.azure.com) in your browser.

If you want to deploy something more complicated than a single container like that, you can go ahead and use a docker-compose.yml file. However, since ACS is only running Docker 1.24, we can't use "docker stack", as this requires version 1.25. Instead, we need to use docker-compose

Ok...I think that was all I had to cover. It is probably just a bunch of stuff you could have figured out on your own, but was hopefully faster to read it here. And to be honest, the post is mostly written with myself in mind. I needed to write this down to sort it all out in my head, and to have a place to come back to when I forget how it is all connected. But hopefully it might help someone else out there as well at some point!

Cheers!

My intro to Docker - Part 5 of something

chris@59north.com — Mon, 18 Sep 2017 14:55:15 +0000

In the previous posts, I have talked about everything from what Docker is, to how you can set up a stack of containers using docker-compose, but all of the posts have been about setting up containers on a single machine. Something that can be really useful, but imagine being able to deploy your containers just as easily to a cluster of machines. That would be awesome!

With Docker Swarm, this is exactly what you can do. You can set up a cluster of Docker hosts, and deploy your containers to them in much the same way that you would deploy to a single machine. How cool is that!

Creating a cluster, or swarm

To be able to try out what it’s like working with a cluster of machines, we need a cluster of machines. and by default, Docker for Windows/Mac includes only a single Docker host when it’s installed. However, it also comes with a tool called docker-machine that can be used to create more hosts very easily.

There is just one thing we need to do before we can create our cluster of hosts. We need to set up a virtual network switch for them to attach to. And to do that, I’m going to use the Hyper-V manager.

Remember that our hosts run in Hyper-V on Windows, so we are dependent on that infrastructure for it to work. On a Mac, the situation is different. So if you are doing this on a Mac, I suggest Googling how to create a virtual switch on a Mac.

In the Hyper-V Manager, right-click the local machine in the menu to the left

and then click Virtual Switch Manager…, followed by Create Virtual Switch. Name the switch something useful, and connect it to an external network of your choice. You might more than one network adapter on your machine. In that case, choose the one that you want the Docker hosts to be connected to.

Personally I named it DockerSwitch, and attached it to my wireless adapter on my laptop

Note: One thing to note about this, is that attaching the hosts to a public network adapter like this will give the hosts new IP addresses everytime you switch network. This will in turn screw up you cluster. But it works well as long as you are just quickly trying this out.

With that switch in place, we can go ahead and create a couple of Docker host machines using the docker-machine tool. A process that is almost too easy to believe. All you have to do, is call docker-machine, passing it the virtualization platform that is being used, the name of the virtual switch to use, and the name to use for the machine. So I’ll go ahead and execute the following

docker-machine create -d hyperv --hyperv-virtual-switch DockerSwitch SwarmManager

using a Powershell window running as an Administrator. This will set up a new Hyper-V based virtual machine using a Boot2Docker ISO, naming it SwarmManager and attaching it to the DockerSwitch virtual switch.

This machine will be the manager of my cluster. That means that it will be the machine that I will execute my Docker commands against. It then makes sure to set up the state in the swarm for us. In the case of starting some new containers, it means that it will either host the container itself, or delegate to a worker in the cluster, depending on load and requirements and so on.

You don’t really have to set up any workers to be able to run the swarm commands that we are going to be running in this post. A one machine cluster is perfectly fine. But it is a little boring. So I’ll go ahead and create one more machine that will acts as a worker, by running the following command

docker-machine create -d hyperv --hyperv-virtual-switch DockerSwitch SwarmWorker01

This will create a second VM called SwarmWorker01, which I’ll set up to be a worker in the swarm.

Next, I need to create the actual swarm. And to do that, I need to run a command that looks like this

docker swarm init

on the manager node. However, it needs to run on the actual host. So to do that, I’ll use docker-machine to SSH into the machine and execute the command. Like this

docker-machine ssh SwarmManager "docker swarm init"

This tells docker-machine to SSH into SwarmManager, and execute “docker swarm init”. This will return some information about how to join the swarm from a worker. It should look similar to this

To add a worker to this swarm, run the following command:
docker swarm join --token SWMTKN-1-0poaqqcljbote3vg8zpl7g68ehrcr3xsqpbth1ckqxnqip6vyd-5vsl5hjgmplhk98lnc9n7og70 192.168.43.16:2377
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

which is pretty descriptive. So let’s go ahead and use docker-machine to execute that on the swarm node by running

docker-machine ssh SwarmWorker01 “docker swarm join --token SWMTKN-1-0poaqqcljbote3vg8zpl7g68ehrcr3xsqpbth1ckqxnqip6vyd-5vsl5hjgmplhk98lnc9n7og70 192.168.43.16:2377”

This should return a simple statement telling you that the node has been joined to the swarm as a worker

These simple commands have now given us a tiny swarm, containing a manager and a single worker node, and it’s now ready for us to go ahead and deploy our containers.

Note: If you want to reconfigure your Docker client to target the SwarmManager host instead of using SSH, you can do that by running docker-machine.exe env SwarmManager | Invoke-Expression. This will set the environment variables needed to reconfigure the Docker client to talk to the SwarmManager instead of the default Docker for Windows Docker host. This is temporary though, and will only affect the current PowerShell window.

Adding images to use in the swarm

The next step is to set up some images that we can use to for our containers. But this time this is going to be a little different. Because, to be able to share images between nodes in the swarm, the images need to be on an external repository. And for this, I’m going to use Docker Hub. But before we get to that, we need an appplication to deploy. And in this case, it will be a simple ASP.NET Core web application. It’s VERY simple. It uses a startup file that looks like this

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.Run(async (context) => {
            await context.Response.WriteAsync("Hello World!");
        })
    }
}

As you can see, it is just a VERY basic application that returns “Hello World” on every incoming request.

And the dockerfile for this application, which is located in the same folder as the application, looks like this

FROM microsoft/aspnetcore-build
COPY . /app
WORKDIR /app
EXPOSE 80
ENTRYPOINT ["dotnet", "run"]

Once I have my application and my dockerfile, I need to build an image by running docker build. So I’ll go ahead and exeucte

docker build . --tag zerokoll/demo_app

This will build an image called zerokoll/demo_app locally on my machine. The “zerokoll” part is my Docker ID. It needs to be named like this to allow me to push it to Docker Hub.

Next I need to push it to Docker Hub, but to do that, I first need to log in by executing

docker login

This requires me to pass in my Docker ID and password.

Once that is done, I can push my demo_app image to Docker Hub by executing

docker push zerokoll/demo_app

This will push the entire image to my repo at Docker Hub, making available to all my swarm nodes.

With that in place, we can go ahead and start a new container in the cluster.

Starting containers in the swarm

However, before we do that, I just want to mention that it is actually called starting a service in the cluster. A service is basically a container running in a swarm, but a service supports some other features like being able to run multiple, load-balanced instances across swarm nodes. So to be correct, we should be talking about setting up some services.

To get services up and running in the swarm, we need to tell the manager what services we want. We can do this in a couple of ways. We can either run commands like docker service create manually, or we do it using using docker-compose.yml files. And since we already know how to use thses, let’s go ahead and use a docker-compose file.

I’ll create a new docker-compose.yml file that starts a container using the image we just created. It should look something like this

version: ‘3'
    services:
        demo_app:
            image: zerokoll/demo_app
            ports:
                - "8080:80"

This will start a new service called demo_app, based on the zerokoll/demo_app image, binding the hosts port 8080 to the containers port 80. However, to “deploy” it to the cluster, we don’t use docker-compose command as we have done before. Instead we use docker stack deploy. And we need to run it on the manager, not our “local” host, which means that we need to copy the yml file to the manager machine, and then call the command on that machine using SSH.

So the first step is to copy the file to the manager using the following command

docker-machine scp docker-compose.yml SwarmManager:~

This will copy the docker-compose.yml file from the local folder to the manager. And then we need to deploy it to the swarm using the following command

docker-machine ssh SwarmManager "docker stack deploy -c docker-compose.yml demo_stack"

This will deploy the “stack” of services defined in the docker-compose file to the swarm.

However, this will take a little while, as the manager first needs to download the image before it can start the service. “Unforuntately” this happens in the background, so it is a bit hard to figure out what is happening. But as soon as is is done , we should be able to browse to our beautiful “Hello World” text by browsing to the swarm manager. And to be able to do that, we need to know the swarm managers IP address. Something that we can find out by running

docker-machine ls

This should give you a list of Docker machines running on you computer, including their IP addresses. So all you need to do to verify that everything is working, is to copy the IP address of the SwarmManager machine and put it into your browsers address bar, appending :8080.

If you want to see what services are running in the swarm, you can run

docker-machine ssh SwarmManager "docker service ls”

This will show you all services running in the swarm. And as you can see, the demo_app service has been named by prefixing it with the stack name demo_stack. If you instead just want to see the services running in the stack called demo_stack, you can run

docker-machine ssh SwarmManager "docker stack ps demo_stack"

And once you have verified that everything is working, and you are ready to tear down your “stack. You can just execute

docker-machine ssh SwarmManager "docker stack rm demo_stack"

This will stop all the services that are currently running in the stack, and remove them, including the containers.

But wouldn’t it be cool if we could see what services are running on what node? Guess what, you can easily do that by adding an extra service to the mix.

Visualizing the containers in the swarm

The only thing we need to do to add some visualization to the, is to add another service/container to the mix. And to do that, we just need to update the docker-compose.yml file like this

version: '3'
    services:
        demo_app:
            image: zerokoll/demo_app
        ports:
            - "8080:80"
        networks:
            - my_network
    visualizer:
        image: dockersamples/visualizer:stable
        ports:
            - "8081:8080"
        volumes:
            - "/var/run/docker.sock:/var/run/docker.sock"
        deploy:
            placement:
                constraints: [node.role == manager]
        networks:
               - my_network
networks:
    my_network:

As you can see, I have made a bunch of changes to the docker-compose.yml file. First of all, I have added a new service called visualizer, which is based on the image dockersamples/visualizer. This is a cool little service that gives us a website where we can see the state of the swarm.

For the visualizer service, I have mapped port 8081 on the swarm to the containers port 8080, as well as set up a volume based on the docker unix socket. However, I have also set up a placement constraint, telling the manager that this service has to run on a swarm node, where the nodes role is manager. The reason for this is that this service depends on information provided by the manager node. So adding this constraint will make sure that whenever this stack is deployed, this service will always be placed on the manager node.

Next, I have just made some things a but more eplicit. Mainly the networking. In this case, I am eplicitly setting up a network called my_network, and adding both the services to that network. If we don’t explicitly tell the manager to set up a network, it will set up a default network, and add all the services to it, which is what happened in the previous version of the file.

So let’s go ahead and run

docker-machine scp docker-compose.yml SwarmManager:~
docker-machine ssh SwarmManager "docker stack deploy -c docker-compose.yml demo_stack"

This will copy across the new docker-compose.yml file, and then deploy the stack to the swarm. And once again, that will take some time, as it first needs to get the dockersamples/visualizer image. But once that is done, you should be able to back to the browser and port 8080 and get that familiar “Hello World” rsponse. However, you should now also be able to go to port 8081 to see the visualization of the nodes and services in the swarm. In my case, i can see the following

This This tells me that I have 2 nodes, the SwarmManager and the SwormWorker01, and the manager runs the demo_stack_visualizer, and the worker runs just an instance of the demo_app. The little green dots in the top left corner of the “service boxes” are also telling me that the instances are up and running.

Note: It took me a minute before I got the screenshot, so the demo_stack_demo_app instance managed to turn green. But it did take a little while to go from red to green as the worker node first needed to pull the image from Docker Hub before it could get it started.

But right now, we are only running a single service besides the visualizer. So it’s going to be a really boring thing to look at. Not to mention that it doesn’t really show any of the cool load balancing features of the swarm. So let’s go ahead and modify the setting for the demo_app service, adding the following

…
services:
    demo_app:
        …
        deploy:
            replicas: 2
…

This tells the swarm manager that it should run 2 instances of the demo_app service in a load balanced fashion.

Unfortunately, we will have no clue that the loadbalancing is taking place at the moment, since the response will be the same from both services. So let’s update the application by adding some information about what host the application is running on. And the easiest way to do this, is by updating the Startup class, changing the response like this

await context.Response.WriteAsync("\"Hello World!\" says " + Environment.MachineName);

Ok, so now that the application will tell us what machine it is running, let’s go ahead and deploy it.

First of all, we need to create a new image, byt running the followinf command

docker build . --tag zerokoll/demo_app

and then push it to Docker Hub by executing

docker push zerokoll/demo_app

Finally,, we need to deploy the updated stack by executing the following commands

docker-machine scp docker-compose.yml SwarmManager:~
docker-machine ssh SwarmManager "docker stack deploy -c docker-compose.yml demo_stack"

This first copies accross the updated docker-compose.yml file, and then deploys it to the swarm, updating the demo_stack stack.

Tip: Pull up the visualizer window before executing the command to let you see what is happening. As you will see, it will take down one service at the time, setting up a new instance before taking down the next.

This time, it only needs to pull down a little bit of data, as most of the layers are common between the 2 versions. So the update should be fast.

Once everything has completed, you should the visualizer should now show you that you have 2 insances, or replicas of the demo_app service running in the swarm. And they should be deployed to different nodes in the swarm. In my case, the visualizer looks like this

Once at least one of the demo_app nodes are green, you should be able to browse to port 8080 and see the host name as part of the greeting. And when both instances are up, refreshing the page might show you the requests being load balanced.

I say may, because on my machine I had to pull up a new incognito browser window to get it to use another node. But I’m not sure that is needed in all cases…

But what if we need to make some changes to the demo_app service? Well, in that case, we can just update the service and re-deploy it. So let’s try that…

First I’ll just update the application in some way. So I’ll go ahead and make a simple change to the reponse, like this

await context.Response.WriteAsync("\"Guten Tag\" says " + Environment.MachineName);

Making the application greet the user in German instead of English.

Then we need to generate a new image

docker build . --tag zerokoll/demo_app

and push it to Docker Hub

docker push zerokoll/demo_app

and then we can go ahead and update the service. We can do this in 2 ways. We can either push a new stack, which will update the service for us, or we can update the individual service by calling docker service update. However, to be able to use docker service update, we need to know the name of the service we want to update. So let’s first query the running services to see what services we have to choose from

docker-machine ssh SwarmManager "docker service ls"

should return something similar to

ID                  NAME                    MODE                REPLICAS            IMAGE                             PORTS
6v8ejov604w7        demo_stack_visualizer   replicated          1/1                 dockersamples/visualizer:stable   *:8081->8080/tcp
mp7eeu6tmvx3        demo_stack_demo_app     replicated          2/2                 demo_app:latest                   *:8080->80/tcp

As you can see, all service names are prefixed with the name of the stack they are part of. This means that the service we want to update is called demo_stack_demo_app, which in turn means that the command we need to execute to update it is

docker-machine ssh SwarmManager "docker service --image zerokoll/demo_app update demo_stack_demo_app"

This will update the demo_stack_demo_app service to use the latest zerokoll/demo_app image. In practice, this means that one service at the time is torn down, and put back up again, using the latest version of the image.

You should now be able to go back to the browser on port 8080, and refresh, and see the greeting in German. If not, give it a couple of seconds and try again. It can take a little while for the services to be updated, depending on the size of the update.

Note: If you pull up the visualization on screen before you run the command, you will see the services being updated. Or rather, you will see the services being taken down one by one, and put back up using the new image.

Once you are done refreshing the browser and looking at the updated response coming from the updated services, you can tear down the whole thing by calling

docker-machine ssh SwarmManager "docker stack rm demo_stack"

And if you want to remove the hosts from the swarm as well, you can execute

docker-machine ssh SwarmWorker01 "docker swarm leave"
docker-machine ssh SwarmManager "docker swarm leave --force"

As you can see, you need to provide a --force when taking the manager out of the swarm. The reason for this is that this takes down the entire swarm. Not something you want to do by mistake.

And if you want to remove the hosts from your machine as well, you can just execute

docker-machine rm SwarmManager
docker-machine rm SwarmWorker01

This should pretty much put your machine back to the state it was in before you started. Well…not quite… You also need to remember to go back to the Hyper-V Manager and remove the virtual switch that was added at the beginning of the post.

That was it for this post… Hopefully you now have a basic understanding of how you can set up a simple swarm, and deploy your stacks to it using docker stack.

My intro to Docker - Part 4 of something

chris@59north.com — Wed, 30 Aug 2017 11:45:18 +0000

In the previous posts about Docker, here, here and here, we’ve looked at what Docker is, how to set up a basic container and how to set up a stack of containers using docker-compose. One thing we haven’t talked about is the fact that most projects use some form of persistent data store, and the most common store, at least in my world, is a relational database of some sort. So this time, I want to cover something that might seem slightly odd…setting up an MS SQL Server…on Linux…in Docker.

Yes, you heard me right… I’m going to show you how to set up an MS SQL Server instance in a Linux-based Docker container. Something that wouldn’t have been possible, in any way, not too long ago, but Microsoft “recently” released a version of MS SQL Server that runs on Linux, which is really cool. And running it in Docker just makes sense!

Running MS SQL Server in a Docker container

Starting a SQL Server instance in a Docker isn’t that hard, but there are a couple of things that need to be set up for it to work.

of all, SQL Server can only run on a machine that has at least 3,25 Gb of memory. And when running Docker for Windows (or Mac), that isn’t the case by default. So the first step is to update the Docker VM host to have more memory. Luckily, this is a piece of cake to do. Just go down to the systray and right-click the little Docker icon (the whale), choose Settings and then Advanced settings. In here, you can just pull the slider to update the available memory to be at least 3,25 Gb, and then click Apply. This will cause the VM that runs in Hyper-V to restart, and when it comes back online, it will have more memory for us to play with.

Note: Don’t go in and update the VM in the Hyper-V manager…

Next, SQL Server requires a couple of environment variables to be set up, for it to start up without any user interaction. First of all, it requires a variable called ACCEPT_EULA, that should be set to Y, to confirm that we accept the EULA. And then we need a admin password to be set up using the SA_PASSWORD variable. So to run a new SQL Server instance, you can just run

docker run --name sql_server -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=MyVeryS3cr3tPassw0rd!' -p 1433:1433 –d microsoft/mssql-server-linux

This will start a new SQL Server instance inside a detached container, mapping port 1433 on the host, to 1433 on the container. This means that once the container is up and running, and SQL Server has started (which takes a few seconds) you can just open a SQL Server Management Studio instance and connect to localhost.
Note: If you already have SQL Server installed on your machine, port 1433 is likely already in use, so you will have to map some other port on the host, and then use that new port when connecting SSMS, using the format <hostname>, <port number>.

And if you don’t want to use SSMS, or you are on a Mac, you can connect to the container interactively, and run queries, using this command

docker exec -it sql_server /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P MyVeryS3cr3tPassw0rd!

This will attach your command line to the SQL Server instance, allowing you to run commands like this

select * from sys.Tables
go

And when you are done, you can just run

exit

to detach.

However, it kind of sucks to have to attach like this, or using SSMS, and set up a database every time you start a container based on the SQL Server image. It would be much nicer to have the database set up for us when the container starts instead. And the easiest way to do this, is to create our own SQL Server Docker image, that contains the start up functionality we need.

Seeding the database

You’ll need to add a couple of files for this to work so I suggest creating a new directory to hold them. Inside that directory, we need a new dockerfile, in which we need to add the following

FROM microsoft/mssql-server-linux

ENV ACCEPT_EULA=Y
ENV MSSQL_SA_PASSWORD=MyPassw0rd!

RUN mkdir -p /app
WORKDIR /app COPY . /app
RUN chmod +x /app/import-data.sh

EXPOSE 1433
ENTRYPOINT ["/bin/bash", "./entrypoint.sh"]

So what’s going on here? Well, first of all, it defines that the image should use the microsoft/mssql-server-linux image as the base image. Then it sets the required environment variables using the ENV keyword. And since I need a set up script and some other files, I go ahead and create a new directory called /app, making it the current working directory using the WORKDIR keyword. The files from the current directory is then added to that directory using the COPY keyword. However, since I’m going to use a shell script, I need to run chmod to set the permissions to allow it to be executed. Finally it exposes port 1433, which is used by SQL, before setting up an entrypoint telling the image to execute the entrypoint.sh script using bash.

That configures the image, but what’s inside the entrypoint.sh file? Well, not much…

/app/import-data.sh & /opt/mssql/bin/sqlservr

It just calls another shell script called import-data.sh, and then starts SQL Server by calling sqlservr. And yes, it needs to be in this order, even if it makes little sense trying to import data before SQL Server has started. But, the last thing being executed has to keep running to keep the container running, and the shell script will only run some commands and then terminate, while sqlservr will block the execution and keep running.

The import-data.sh file isn’t much more complicated

echo "Sleeping"
sleep 20s

echo "Setting up table"
/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P MyPassw0rd! -d master -i setup.sql

echo "Importing data in Products table"
/opt/mssql-tools/bin/bcp DemoData.dbo.Products in "/app/Products.csv" -c -t',' -S localhost -U sa -P MyPassw0rd!

Note: Currently, there is no way to add start up scripts to SQL Server for Linux, but hopefully there will be in the future. That way we won’t have to do a stupid sleep to get things to work…

After the 20 seconds, it uses sqlcmd to attach to the local SQL Server instance, using the sa account, and then runs a script called setup.sql, which we’ll have a look at in a minute… And finally it uses bcp to import the contents of a file called Products.csv into a table called Products in a database called DemoData database, which is created in the setup.sql script that looks like this

CREATE DATABASE DemoData;
GO

USE DemoData;
GO

CREATE TABLE Products (ID int, ProductName nvarchar(max));
GO

and just to be thorough, and show it all, the Products.csv file looks like this

1,Skateboard
2,Kite
3,Parachute
4,Computer

With the dockerfile in place, we can create a new image by running

docker build --tag sql_server .

naming the image sql_server. Finally, we and start up a new container based on that image, by executing

docker run –it –p 1433:1433 --rm sql_server

This should end up with a running SQL Server instance, with a database called DemoData, containing a table called Products with some data. And as long as you don’t stop the container, you should be able to connect to it as usual using SSMS (or whatever tool you normally use) and look at the database.

However…this set up kind of sucks! It will set up a new database, with the same hardcoded data, every time you spin up a new container based on this image. Not playing very well together with the idea that containers can be ephemeral, and be taken down and moved around at any given time… Unless, all you need is a database with a fixed dataset. But in most cases, you want to be able to use your database to store stuff, but adding, updating and removing things. So how do we go about solving this?

Adding persistence

To be able to persist data between when containers are moved around, updated etc, we need a storage location that isn’t tied to the container. Anything inside a container will be blown away when the container is deleted, which is what will happen if the container is moved for example. So in general, we don’t want to persist permanent things inside the container. Instead we want to persist permanent things external to the container.

There are 2 different ways to add external storage to a container. The first way is to bind something called a volume to the container, which basically means that we take a directory on the host, or somewhere persistent, and map it to a path inside the container.

Note: If you come from a Windows background, which I guess you probably do, you need to remember that Linux doesn’t use drive letters etc to access files. Instead they use mount points, which is basically just a path where some form of storage is located. So you could see a bound volume as a mapped network drive in Windows, but the mapped drive just gets a path…

Note 2: This doesn’t work for this special scenario for Docker for Mac. Binding volumes work, but apparently SQL has some issues with it. More information can be found here. So if you are on a Mac, you need to look at the “Alternate persistence” section below.

Note 3: Even if you are on a Windows machine, it might be a good idea to have a look at the “Alternate persistence” section below as well…

There are different drivers out there that allow you to use different storage mechanisms for your bound volumes, but for this demo, I’ll use a directory on the host as a volume.

To add a volume using the docker run command, you just need to add a –v parameter with the value set to <host directory>:<container path>. So running

docker run –v c:\DockerVolume\:/dockervolume myimage

Will start a new container using the myimage image, with the path /dockervolume/ inside the container, mapped to the c:\DockerVolume\ directory on the host. So anything inside the c:\DockerVolume\ directory will be available inside the container, and anything written to /dockervolume/ in the container, will be persisted to the c:\DockerVolume\ directory. And since that is a directory on the host, which hopefully won’t disappear, the data will be persisted between container starts.

Using this, we can go ahead and make the SQL storage a bit better. So, iInstead of creating a new database in every container, we can attach an existing database on start instead.

Step one, is to create the new database in some way. In my case, I just used SSMS and my local SQL Server instance to create a new database that replicates the one used in the previous example. Then I detached that database from my local SQL Server instance. This gave me a DemoData.mdf and DemoData_log.ldf file located somewhere similar to C:\Program Files\Microsoft SQL Server\MSSQL13.SQLEXPRESS\MSSQL\DATA (depends on what instance name you are using and so on…but you get the point). Then copied those 2 files, to a new directory called c:\MyDockerVolume\.

With the mdf and ldf files in place, we need to update the set up script to attach them to SQL Server, instead of creating a new database. To start out, we can update the setup.sh file to this

echo "Sleeping"
sleep 20s

echo "Attaching Database"
/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P MyPassw0rd! -d master -i setup.sql
echo "Done Attaching Database"

As you can see, I have removed the CSV-file import, and then we need to update the setup.sql to this

USE [master]
GO

CREATE DATABASE [DemoData]
ON ( FILENAME = N'/sql_storage/DemoData.mdf' ), ( FILENAME = N'/sql_storage/DemoData_log.ldf' )
FOR ATTACH
GO

It uses CREATE DATABASE to create a new database called DemoData, attaching the DemoData.mdf and DemoData_log.ldf files from a directory called /sql_storage/. This means that when the container starts up, it will start SQL Server, and then run the setup.sql script, setting up a new database using the two SQL files. All we need to remember is to make sure that we add a volume that contains the files.
So to try this out, we first need to create a new image since the scripts have changed

docker build --tag sql_mounted .

and then we can create a new container using that new image

docker run -it -p 1433:1433 -v c:\MyDockerVolume:/sql_storage --rm sql_mounted

Note: Make sure you map the correct folder. The above command maps c:\DockerVolume\ which is just what I use…

Tip: If you get problems opening your files in the container, make sure that all the file permissions are set up properly on the host…

As long as you container is up and running, you should be able to connect through it using SSMS or whatever tool you use to work with SQL Server. And if you add or remove any data, it will be persisted even if you remove the container and start it back up again. So you should be good to go.

Alternate persistence

The second way to persist files between container instances, is by using something called a data volume container. This is basically a mapped storage location called a volume, managed by Docker. And the way you set that up, is by first creating a new volume by calling

docker volume create sql_data

This will create a new empty volume called sql_data.

Then you need to add the files you want in the volume, by copying them from somewhere. In this case, the host. However, to do that, you need to create a container and attach the volume to that, and then copy the files to the volume through that container.

So, to do that, you can run

docker run -v sql_data:/sql_storage --name temp alpine

to create a new container called temp, with the sql_data volume attached to /sql_storage/.

Next, the files are copied using docker, by calling

docker cp ./Data/DemoData.mdf temp:/sql_storage docker cp ./Data/DemoData_log.ldf temp:/sql_storage

which will copy the DemoData.mdf and DemoData_log.ldf files to the containers /sql_data/ directory, which then maps to the sql_data volume. And when that is done, you can go ahead and delete the temporary container

docker rm temp

Now, the volume should contain all of the required files, so running

docker run -it -p 1433:1433 –v sql_data:/sql_storage --rm sql_mounted

will start up a new SQL container, but this time with the /sql_storage/ path mapped to the volume we just created.

The volume is then persisted separately from the container. So when the container is removed, the volume is persisted, read for re-use.

Note: For a real scenario, you would just skip the -it and add -d to have the container running in the background instead.

To view your volumes on the host, just run

docker volume ls

and if you want to remove a volume, you just run

docker volume rm <volume name>

That’s pretty much it! Hopefully you now have an idea of how to store your data permanently, as well as how you can get SQL Server up and running inside a Docker container running Linux. Who would have thought A, that I would ever write about Linux and command lines, and B, about running Microsoft SQL Server on Linux!? It’s a brave new world!

The next post covers Docker Swarm and how we can deploy to a cluster of machines. Very cool stuff!

My intro to Docker - Part 3 of something

chris@59north.com — Fri, 25 Aug 2017 13:54:51 +0000

So far in this little blog series about Docker, I have covered what Docker is, how it works, how to get a container up and running using pre-built images, as well as your own images. But so far, it has all been about setting up a single container with some form of application running inside it. What if we have a more complicated scenario? What if we have a couple of different things we want to run together? Maybe we want to run our ASP.NET Core app that we built in the previous post behind an nginx instance instead of exposing the Kestrel server to the internet… Well, obviously Docker has us covered.

However, before we go any further, I just want to mention that I will only be covering something called docker-compose in this post. This can be used to create a stack of containers that are set started and stopped together. I will not be covering distributing the application accross several nodes this time. There will be more about that later. And even if that is probably the end goal in a lot of cases, being able to just run on a single host can be useful as well. Especially while developing stuff.

What is docker-compose?

When you installed Docker for Windows or Docker for Mac, you automatically got some extra tools installed. One of them is docker-compose, which is a tool for setting up several containers together in a stack, while configuring their network etc. Basically setting up and configuring a set of containers/apps that work together.

It does this by using a file called docker-compose.yml. At least it’s called that by default. You can pass in another name asa parameter to docker-compose if you want to… And as the file extension hints, it is a YAML file. This means that it defines the services we want to have in our application stack using YAML syntax. And yes, we are now talking about services. A service is basically a container. It is a bit more complicated that that, but for this you can see it as a container.

Configuring an application stack using docker-compose

In the previous post, I created a simple ASP.NET Core application that we could run in a container. Then we created an image called myimage, containing that application. What I want now, is to protect that application behind an nginx reverse proxy server. This means that I need 2 containers. One running nginx, exposing a port the a client can browse to, and one running the actual application, which nginx proxies requests to.

But before I can set up my stack, I need to set up the nginx image I want to use. And I want to have that set up placed in a sibling directory to the application. So I’ll create the following folder structure

DockerDemo
- DockerApp
- nginx

And inside the nginx folder I create 2 files. One called nginx.conf and one called dockerfile. Inside the nginx.conf I need to add the configuration that nginx should use. And in this case, it looks like this

worker_processes 1;
events { worker_connections 1024; }
http {
    sendfile on;
    upstream web {
        server web:80;
    }
    server {
        listen 80;
        location / {
            proxy_pass http://web;
            proxy_redirect off;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Host $server_name;
        }
    }
}

The only thing that is really interesting here is the “proxy_pass http://web”. This is the line that tells nginx to proxy all calls to a server called “web”. This will be a DNS name set up by docker-compose, and represent the container running the ASP.NET Core app.

The dockerfile contains the following

FROM nginx:alpine
COPY nginx.conf /etc/nginx/nginx.conf

which tells Docker that it should use the nginx:alpine image as the base image, and then just add the nginx.conf file to the /etc/nginx/ folder.

That’s it for setting up the nginx image. The next step is to set up the docker-compose stuff to get our stack up and running. So I start out by creating a new file called docker-compose.yml in the DockerDemo root folder. I need it to be a sibling to both the DockerApp and nginx folders. It’s in this file I’m going to define the services that make up my application stack. But before I can do that, I need to define what version this file uses… So I’ll add a version entry like this

version: 3

Then I need to configure my services. So I’ll start out with the nginx service, which I set up by adding the following

services:
    nginx:
        build:
             context: ./nginx
        ports:
             - "8080:80"

This tells docker-compose that I want a service called nginx, built using the dockerfile in the nginx directory, and mapping the port 8080 on the host to port 80 on the container.

FInally, I add the web service as well, by adding

services:
    …
    web:
        image: myimage

As you can see here, I’m adding a service called web that should be based on the image called myimage. And that’s actually everything I need. docker-compose will automatically set up a network for all the services defined, and make sure that they can communicate with eachother using the service names. So when nginx proxies calls to http://web, it redirects to this service in this application stack.

With all my files in place I can go ahead and call

docker-compose up -d

to start up the required services in detached mode, which means that it wont attach the output from the containers to your terminal. If you want to see the output from the containers, which can be really helpful for debugging, just omit the -d flag.

Once it has built the nginx image and started up both the containers, you can just open a browser and browse to http://localhost:8080 to see the result. It’s not very impressive as such, but remember that you just set up a reverse proxy server and a 2 service application stack in just a couple of minutes. And adding a SQL database and/or redis cache is just as easy.

When you are done playing around with the application, you can just run

docker-compose down

to stop all the services and tear down the containers. The only thing left is an nginx image called dockerdemo_nginx, which is the one that was automatically created for us by docker-compose. If you want to get rid of it, just run

docker rmi dockerdemo_nginx

That’s it!

There is obviously a whole heap more to docker-compose, but now you at least know the basics of how you can set up a stack of services that can all communicate with eachother in an easy way.

In the next post I’ll be looking at how we can set up a Microsoft SQL Server instance inside of a Docker container. Yes…you read it right…a Microsoft SQL Server running on Linux in a Docker container!

Going green…a.k.a. “Hello tretton37!”

chris@59north.com — Fri, 25 Aug 2017 12:30:28 +0000

As of this Monday, I’m officially working as a ninja at tretton37 in Stockholm. And for those of you who don’t speak Swedish, tretton37 means thirteen37, which is just an awesome name for an IT company.

So what is a ninja? Well, it is pretty much just an IT consultant as such, but the company doesn’t like the idea of that word. At least in Sweden, it has basically been reduced to be the same as a hired resource. The word consultant isn’t about consulting, giving advice and offering knowledge anymore. So to mitigate that, the common name for a person that works at tretton37 is “ninja”. The focus is to give our clients more than just a resource that can code. It’s about more than that. It’s about giving tips and ideas, and go beyond just building something, and instead take a bigger responsibility for the solution. Making sure that we do our best to give the client what they need and not just what they ask for. It’s about listening to what they want to accomplish, and not what they want us to build.

This view of what we should be doing correlates well with my own view on what we should be doing. So I’m very excited to be here, and hopefully there are some cool projects for me here in the future. With some happy clients at the end…

While I wait for that though…I’ll take this chance to catch up on some blogging and things, with the goal being that my blog will once again be a living thing that actually provides value.

My intro to Docker - Part 2 of something

chris@59north.com — Fri, 25 Aug 2017 09:02:24 +0000

In the previous post, I talked a bit about what Docker is, how it works, and so on. And I even got to the point of showing how you can create and start containers using existing images from Docker Hub. However, just downloading images and running containers like that, is not very useful. Sure, as a Microsoft dev, it's kind of cool to start up a Linux container and try out some leet Linux commands in bash. But other than that it is a little limiting. So I thought I would have a look at the next steps involved in making this and actually useful thing…

Creating something to host in a container

The first step in using Docker is to have something that should run inside of our containers. And since I am a .NET developer, and .NET Core has Linux support, I thought I would write a small ASP.NET Core application to run in my container.

Note: Before you can run this, you need to install the .NET Core SDK…

Step one is to create an ASP.NET Core application. So I'll open up a command line window and navigate somewhere where I want to store my files. And then I'll run

mkdir DockerApp
cd DockerApp
dotnet new web

This will create a new ASP.NET Core application for us. The next step is to set it up to do something. And to do that, you can use whatever editor or IDE you want, but I'll use VS Code, so I'll just go and type

code .

And since I just want to create the simplest possible ASP.NET MVC app, I'll go ahead and add MVC in the Startup

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment()) {
        app.UseDeveloperExceptionPage();
    }
    app.UseMvc();
     app.Run(async (context) => { await context.Response.WriteAsync("Hello World!"); });
}

Then I'll add a new folder called Controllers, and a class inside of it called HomeController that looks like this

using Microsoft.AspNetCore.Mvc;
namespace DockerApp.Controllers {
    public class HomeController : Controller {
        [Route("/")]
        public IActionResult Index() {
            return View(); }
        }
}

And then I'll add the actual view by adding a folder called Views, and inside of that one called Home, and inside that a Razor view called Index.cshtml that looks like this

<!DOCTYPE html>
<html>
      <head>
        <title>DockerApp</title>
     </head>
     <body>
         <h1>Hello from Docker</h1>
     </body>
</html>

All of that is stock standard ASP.NET stuff, so hopefully you already knew how to do this. But I thought I would cover it anyway…

To run this application from the command line, all you have to do is go to the DockerApp folder and type

dotnet run

This will automatically compile your application and start an HTTP server that hosts you application on port 5000.

Note: The port 500 is the default port used by default. This can be changed using an environment variable called ASPNETCORE_URLS

Creating your own images

Now that we have an app that we want to run as a container, we want to package it up in an image, that we can then use to start a container from. There are 2 ways to do this.

Option 1 is to do it interactively. This means that we start up a container based on the image we want to use as our base, passing in -it, to make it interactive. Then we configure and set everything up that we need inside that container. And finally, we call docker commit [container name] to create an image based on that container.

Option 2 is to create a dockerfile, and use that to build an image. And since option 1 isn't recommended for several reasons, I'll focus on this instead.

So I'll go ahead and create a file called dockerfile. And being a Windows person, I normally just create it using Explorer, but if you want to do it in the command line like a "real developer", you can run the following command

touch dockerfile

Note: This requires that touch is in your path. The easiest way is to have Git installed, and add C:\Program Files\Git\usr\bin to your path… Or just use Explorer…

Ok, so what are we doing with this dockerfile? Well, this file defines how to set up the image that you want. It starts out by saying what image it should use as a base, and includes all the commands that need to be run, and files that need to be copied and so on, to make create the state that you want on your image.

So the first thing we need to do is to define what image we want to use as our base, by using the FROM keyword. And since I am doing an ASP.NET Core application, that is run using "dotnet run", I need an image that has the .NET Core SDK on it. Luckily, Microsoft has one of those for us called microsoft/aspnetcore-build. So I'll put this

FROM microsoft/aspnetcore-build

at the top of my file…

Then I need to tell it that I want to include everything inside the folder I am currently in. And I'll do that using the COPY keyword.

Note: There is also an ADD keyword which does kind of the same thing, but it will also expand tar files and a few other things. COPY will do just that…

The COPY command takes 2 arguments. The source and the target inside the container. And remember, the image is Linux-based, so it doesn't have a drive letter and so on. Instead it just has "root folders". So I'll add

COPY . /app

To copy ".", which means current directory, to "/app" in the image.

Then I want to set this directory as the working directory, meaning that all commands executed will have this as the active directory. And this is done using the WORKDIR keyword like this

WORKDIR /app

And then I want to specify that my container will expose a port, using the EXPOSE keyword like this

EXPOSE 80

Wait…what!? The ASP.NET application used port 5000…didn't it? Well, it _did_. Inside the microsoft/aspnetcore-build image, the environment variable called ASPNETCORE_URLS is set to http://+:80, which tells ASP.NET Core to use that port instead of the default 5000. So that is what we want to expose…

The other option is to change the ASPNETCORE_URLS environment variable using the ENV keyword, and then expose whatever port you want. Like this

ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080

But I'll stick to using port 80.

Note: The fact that your container exposes port 80 doesn't mean that it will conflict with anything on port 80 on the host. Exposing a port just exposes it from the container, on the container's network interface. To have it exposed on the host requires us to specifically order Docker to do so, as you will see later on.

And finally, I add an entrypoint. Basically the command to run when starting a container based on this image. And I do that by adding

ENTRYPOINT ["dotnet", "run"]

There are 2 different syntaxes for this. One is this JSON array based syntax called exec form, which is preferred. The other one is called shell form, and is written just writing it like you would on the command prompt… Like this

ENTRYPOINT dotnet run

Sidenote - ENTRYPOINT and CMD

Oh shiny! I’m just going to go into some detail about this, because there are some finer details that might be interesting to note with this…

The JSON array syntax has the executable as the first entry in the array, and then passes any parameters as individual entries in the array. The downside to this is that it doesn't go through a shell, so it won't do environment variable substitution for example. So running something like

ENTRYPOINT ["echo", "$ASPNETCORE_URLS"]

won't echo out the value of the ASPNETCORE_URLS environment variable.

And the second "but" is that when you run this container, and pass in a parameter at the end of the "docker run" command, it will actually not change the executable that is being run, instead it adds the parameter as a parameter to the executable defined in the ENTRYPOINT.

On the other hand, running in shell form, you will run your command under /bin/sh -c. So it will do environment variable substitution etc. But…it won't handle any passed in parameters from the "docker run" command…

There are more fine points in the choice between exec form and shell form. But you will have to read up on the on the Docker docs.

It's also worth mentioning a keyword called CMD now as well. I won't use it, but I still want to cover it, because it can be somewhat confusing…

CMD also has both exec form and shell form, and works pretty much just like ENTRYPOINT. BUT…it is only defaults. Anything set using a CMD keyword will be the default parameters, but overridden if parameters are passed in when using the "docker run" command.

CMD can be used in 2 ways (3 if you count exec and shell form as 2 different ways). It can be used just like the instead of the ENTRYPOINT, telling the container what should happen when it starts, but still leave it open to be changed when starting the container. For example

CMD ["dotnet", "run"]

CMD dotnet run

This will cause "dotnet run" to be executed at the start of the container, either on its own, or through "bin/sh -c" depending on form. But it allows me to pass in a new startup executable when starting the container.

Remember: This requires you to NOT have an ENTRYPOINT in your file.

If you have an ENTRYPOINT as well, the CMD will end up just being parameters passed to the entrypoint executable by default. And any passed in parameters from "docker run" will replace the defaults and be passed to the entrypoint instead.

This gives us a bit of flexibility for how our image allows the user to use it when starting the container.

I don't need any CMD in this case, but I found it reasonable to cover it here as well…

Note: The last little thing to mention is that it IS possible to change the entrypoint when running "docker run" by passing in --entrypoint flag.

Creating your own image - back on track

Ok…after that side note on ENTRYPOINT and CMD and stuff, it is time to move on…

Now that we have a dockerfile that looks like this

FROM microsoft/aspnetcore-build
COPY . /app
WORKDIR /app
EXPOSE 80
ENTRYPOINT ["dotnet", "run"]

So we can now go and build an image. To do this, you go back to the terminal and run

docker build -t myimage .

Hint: If you get a weird exception about unexpected characters, make sure that your file is in UTF-8. If you create your dockerfile using the command line, or PowerShell, the file will be in UTF-16 and will need re-saving in UTF-8…

This will tell Docker to build an image based on your file, and name it myimage. So, after running that command, if you run

docker images

you will see an image called myimage in the list.

Extra: What this will really do, is that it will automatically spin up the base image, and then execute the first command. It will then stop that container and save that storage layer as its own layer. It then starts a new container based on that layer, and executes the next command, and then stops and saves. It then keeps doing that until all commands have executed. At least that is the way I understand it. But the technical details aren't that important to be honest. Just knowing that in the end, you will have an image that looks just like you want every time you build it using that dockerfile is the important part. But…if the build fails, it will leave the container at the last layer, making it possible for you to start it up and attach to it, and figure out what went wrong, which can be really helpful…

And with our new image in place, we can go ahead and run

docker run --rm -d -p 8080:80 --name web myimage

This will start a container based on the newly created image, mapping the hosts port 8080 to the containers port 80, naming it to web, and making sure the container is removed when it is stopped. So opening up a browser and browsing to http://localhost:8080, allows you to browse the application running inside the container.

And to stop it when you are done, you call

docker stop web

which will also remove the container since we added --rm.

That’s it for this time. The next post covers how you can set up mutliple containers and have them work together to create more complex applications.

My intro to Docker - Part 1 of something

chris@59north.com — Tue, 22 Aug 2017 13:49:39 +0000

It’s been quite a while since I blogged, and there are several reasons for this. First of all, I haven’t really had the time, but I also haven’t really found a topic that I feel passionate enough about to blog about. But having played around with Docker, I now have! So I thought I would jot down some stuff about Docker… If nothing else, it gives me a away to come back to what I used to know when I have forgotten all of it again…

What is Docker?

The first thing to cover is what Docker really is. I have seen a lot of explanations, both of what it is, and why it is so good. But I have had a hard time grasping it in the way that it has been explained to me. So here is my explanation. And by my explanation, I mean the way I think about it. It might not be 100% correct from an implementation point of view, but it is the way I see it…

Many people ask what the difference is between Virtual Machines and Docker containers, so I thought I would take that viewpoint.

When we run VMs, vi basically emulate all the hardware of the machine, including a virtual hard drive, and then boot an operating system from that virtual HDD inside of our existing operating system. So we are booting up a full machine, as we normally would, but all the hardware that it runs on is just virtual stuff from the host. This way, we can run many machines on one physical machine, but each virtual machine is a full machine with an OS and so on. Docker is different…

When we run Docker, we have our existing operating system as the base, and then create a area on top of that where our Docker container runs. It still uses the same operating system, but it’s isolated from everything else on the host, so that it can’t interact with the other things installed on the machine. That way, we don’t have to boot up a whole operating system, because that is already booted up with the host. Instead, all we need to do is set up a context that is isolated from the rest of the machine, and have our application run in there. Inside that context, we can then set up the environment that is needed for our application to run. But the main thing is that it doesn’t run its own OS, it just runs in an isolated context on top of the host.

Inside the container, it is a lot like differential disks that are used when running virtual machines. A diff disk contains all the changes from base disk to the current state. So you start out with a base disk that has all the “base” information. The base disk could for example be a disk that contains a clean Windows server install. Then you add a disk on top of that, and install IIS. That second disk only contains the added/changed bytes that were required to install IIS. And then on top of that you might add another diff disk that contains your application. And that disk only contains the bytes needed for that… Slowly building up to what you need. However, in the end, the disks are kind of mashed together, and booted up like a full server. But you can for example use the same base disk for multiple other diff disks. So the WIndows Server base disk could be used for all VMs running on that Windows version.

In Docker, your initial base disk is actually your own operating system, or the host. In most cases that would be your Linux machine, but with Windows Server 2016 you can use Windows containers as well. And then your images are basically diff disks on top of your empty host operating system. But it isn’t based on the actual host disk, with all the installed applications and so on. Instead, it’s based on a clean/empty version of that OS disk. Basically the raw OS part of your hosts.

That means that we don’t have to boot up the server to get everything running. Instead, we can use the hosts OS, and then start a new isolated context with the “diff disks” added on top of the empty OS. This makes it MUCH faster to start a container, compared to starting a physical or virtual machine.

This is also why you can’t run Windows containers on a Linux host and vice versa. At least at the moment. In the near future, it seems like you will be able to run Linux containers on Windows. But that is done through some magic and virtualization.

In Docker, we don’t talk about differential disks though. We talk about images. But an image is basically like a diff disk. It contains all the changes you want to do on top of the host OS for your application. And just as in my previous example, you could create an image that contained IIS. And then add another image based on that image, that contains your application.

Kind of like this

My visualization skills might not be the best, but what I’m trying to show is that at the bottom, we have the physical, or virtual machine, that will be the host. On top of that, we have the host operating system. And in that OS, we might have files and apps that we have installed on the machine, but it also contains a container (green). The container has 2 images (orange) “added on top of” the host OS. In this case, one image that adds IIS, and then one on top of that includes the actual application that I want to host. But the container is completely isolated from the installed apps and files on the host. It even has its own network. So the isolation is pretty complete, unless we go in and mess with it.

This is a very simple example, and also potentially stupid one, as I choose to use IIS. Normally, you would probably use Apache or nginx for the example, as most Docker stuff is Linux based. But I thought that it might be a little easier to grasp using Microsoft-centric technologies. And I consider it simple since the example only runs one container on the host. In most cases you would run multiple containers on the same host, all isolated from eachother. This enables much better utilization of resources on the host, and higher density of applications on each machine.

Images and containers…?

As I explained in the previous section, a Docker image is a lot like a diff disk. It contains the bytes that needs to be added to get the environment you need inside your container. And the cool thing is that there are public repositories containing images for you to use. This makes it really easy to get started with new stuff. If you want to play around with Redis for eample, you just pull down the Redis image to your machine, and start a container based on that image, and all of the sudden you have Redis running with a default configuration on your machine. No installation. Not configuration. And no risk of messing up your machine.

So the image contains the bytes needed to get your environment as you need it to run your application. And it’s based on some other image, or the host OS. The image could be a Redis install with default configuration, or maybe Apache, or maybe just an image preloaded with the stuff you need to run .NET Core on Linux. Either way it is just a predefined set up of the environment you need.

The image is then used to start containers. So you don’t start or run the image as you would start a VM by using the disk. Instead, you start/run a container based on that image. So the image is just the blueprint for the environment that you want inside of your container, and it’s immutable. So you can start as many containers as you want based on the same image. Each container will use the image to set up the environment, and then start whatever processes are configured inside that environment, but the container will never change the image. Any writes inside the container writes to another layer on top of the image…

Installation

The first step to getting started with Docker is to install it on your machine. And since you are on my blog, I’m assuming that you are running Windows, or maybe Mac. That means that you want to install Docker for Windows or Docker for Mac. These are both apps that run on your Windows or Mac, enabling Docker. On the Windows side, it uses Hyper-V to host a Linux VM that runs Docker for us, and on the Mac side, it does something as well… I don’t actually know, but I assume it uses some form of Mac based virtualization to host a Linux machine with Docker.

Once your have either of these installed, and started, you can start using Docker. I use Windows, so I will be using PowerShell to run my Docker commands, but it should be pretty much identical if you do it in the Terminal on a Mac…

The first thing you can try, just to verify that everything is working, is to run

docker version

This will tell you what version of Docker you are running both on the server, and on the client. As well as some other stuff.

If you don’t get a print out telling you that, something is wrong…

Getting images and setting up a container

Next, you can try and run

docker images

This will show you what images you have installed on your machine. I assume that you get very little back since you just installed it. And by very little, I mean nothing. But to be honest, I’m not 100% sure of what you get by default when you install it. But either way, let’s try and pull down a small and simple base image that we can try to run.

Images are stored in repositories, either public or private, or local. When you ran docker images, you asked Docker to list all images in the local repository. But there is also a huge public Docker repo collection called Docker Hub. This is a place where people upload useful images for the public to use. And the image I want, is a tiny one called alpine, which is a 5Mb Alpine Linux image.

There are two ways to pull an image from a Docker Hub repo. Either, you just request Docker to set up a container based on the image you want, and Docker automatically pulls it down for you if you don’t have it, like this

docker run -it alpine

or, you can manually pull it down to your machine first, and then run it like this

docker pull alpine
docker run -it alpine

Either way, it will pull down the alpine docker image to the local host, set up a new container based on that image, and attach the input and output from that containers terminal to your PowerShell window. So after running the docker run command, you can go ahead and run whatever Linux Shell command you want inside that container… And when you are done, you just type exit, to exit the process, which causes the container to stop.

Note: When pulling down the image, it mentions that it is using default tag “latest”. “Latest” in this case is the “version” of the image. All images in a repo has a tag, or version. By default, the last image uploaded to a repo gets the “latest” tag. This way, you can ask to get a specific version of an image in a repo, or just leave it out, and get the latest by default. And since I don’t care about what version of the alpine image I get, I just ignore the tag for now to get the latest.

So, what am I really doing here? Well…the docker pull alpine is pretty self explanatory I think. But the run one is a bit more complicated as I have added some options to that command.

docker run, tells the Docker client to use the run command, which sets up, and start, a new container. The simplest version of that command is just

docker run <IMAGE NAME>

This will set up a new container using the defined image, and start it. However, if you do that with the alpine image, it will do nothing. It will start the container, but nothing is happening inside it, so Docker will just stop it straight away.

This isn’t very useful for this image. But you can also give it a command to run when it starts, which can be useful. Like this

docker run alpine ls

This will set up a new container based on alpine, start the container, run the ls command, output the returned result, and then consider the command completed and stop the container again.

So what is the --it option? Well, first of all, it is a concatenated version of -i -t, and it means that you want to attach to both the input and output of the running container, allowing your to execute commands inside the container. So when the container starts, the PowerShell prompt turns into a remote prompt for the Linux container you are running.

Listing and removing containers

Starting up and playing around with containers is fun, but when you run a container like this, once it stops, it isn’t actually deleted.

If you want to see all the containers on your machine, you use the ps command like this

docker ps

This will list all the running containers on your machine.

In this case, it will probably be empty, because all of your containers have been stopped. But if you tell it to list ALL the containers like this

docker ps -a

you probably get a list of containers that are stopped.

The list includes the containers id, the image is based on, the command that is run when it starts, when it was created, current status, ports and the name of the container. A good set of information about the container…

If you want to clean up the list, and free some space on your machine, you can remove a container by running the rm command.

docker rm <CONTAINER ID/NAME>

All containers get a unique id, as well as a name. The name is an auto generated 2 part name if you don’t manually set one, which is a little easier to work with than the auto generated id. You can use either when you remove a container though. And if you use the id, you only need to define enough of the characters of the id for it to be unique. You don’t need to use all…

Ever so often you end up starting up and playing around with a containers for a very short time, while trying something out. Having to manually remove it after just trying something out, can be a bit tedious. So you can actually automate the removal if you want, by adding the option --rm to the run command. Like this

docker run –it --rm alpine

This way, you tell Docker that you want it to remove the container as soon as it stops, so you don’t end up with a heap of useless containers on your machine.

This is a nice convenience thing, but beware, once in a while you might wish that your test container hadn’t been removed…

That was it for this post. In the next post I’ll look at creating you rown images.

Setting Up Continuous Deployment of an ASP.NET App with Gulp from VSTS to an Azure Web App using Scripted Build Definitions

chris@59north.com — Fri, 08 Jan 2016 08:21:11 +0000

A few weeks ago, I wrote a couple of blog posts on how to set up continuous deployment to Azure Web Apps, and how to get Gulp to run as a part of it. I covered how to do it from GitHub using Kudu, and how to do it from VSTS using XAML-based build definitions. However, I never got around to do a post about how to do it using the new scripted build definitions in VSTS. So that is why this post is going to be about!

The Application

The application I’ll be working with, is the same on that I have been using in the previous posts. So if you haven’t read them, you might want to go and have a look at them. Or, at least the first part of the first post, which includes the description of the application in use. Without that knowledge, this post might be a bit hard to follow…

If you don’t feel like reading more than you need to, the basics are these. It’s an ASP.NET web application that uses TypeScript and LESS, and Gulp for generating transpiled, bundled and minified files versions of these resources. The files are read from the Styles and Scripts directories, and built to a dist directory using the default” task in Gulp. The source code for the whole project, is placed in a Src directory in the root of the repo…and the application is called DeploymentDemo.

I think that should be enough to figure out most of the workings of the application…if not, read the first post!

Setting up a new build

Ok, so the first step is to set up a new build in our VSTS environment. And to do this, all you need to do, is to log into visualstudio.com, go to your project and click the “Build” tab

Next, click the fat, green plus sign, which gives you a modal window where you can select a template for the build definition you are about to create. However, as I’m not just going to build my application, but also deploy it, I will click on the “Deployment” tab. And since I am going to deploy an Azure Web App, I select the “Azure Website” template and click next.

Note: Yes, Microsoft probably should rename this template, but that doesn’t really matter. It will still do the right thing.

Warning: If you go to the Azure portal and set up CD from there, you will actually get a XAML-based build definition, and not a scripted one. So you have to do it from in here.

Note: VSTS has a preview feature right now, where you split up the build and deployment steps into multiple steps. However, even if this is a good idea, I am just going to keep it simple and do it as a one-step procedure.

On the next screen, you get to select where the source code should come from. In this case, I’ll choose Git, as my solution is stored in a Git-based VSTS project. And after that, I just make sure that the right repo and branch is selected.

Finally, I make sure to check the “Continuous integration…”-checkbox, making sure that the build is run every time I push a change.

That’s it! Just click “Create” to create build definition!

Note: In this window you are also asked what agent queue to use by default. In this example, I’ll leave it on “Hosted”. This will give me a build agent hosted by Microsoft, which is nice. However, this solution can actually be a bit slow at times, and limited, as you only get a certain amount of minutes of free builds. So if you run into any of these problems, you can always opt in to having your own build agent in a VM in Azure. This way you get dedicated resources to do builds. Just keep in mind that the build agent will incur an extra cost.

Once that is done, you get a build definition that looks like this

Or at least you did when I wrote this post…

As you can see, the steps included are:

1. Visual Studio Build – A step that builds a Visual Studio solution

2. Visual Studio Test – A step that runs tests in the solution and makes sure that failing tests fail the build

3. Azure Web App Deployment – A step that publishes the build web application to a Web App in Azure

4. Index Sources & Publish Symbols – A step that creates and published pdb-files

5. Copy and Publish Artifacts – A step that copies build artifacts generated by the previous steps to a specified location

Note: Where is the step that downloads the source from the Git repo? Well, that is actually not its own step. It is part of the definition, and can be found under the “Repository” tab at the top of the screen.

In this case however, I just want to build and deploy my app. I don’t plan on running any tests, or generate pdb:s etc, so I’m just going to remove some of the steps… To be honest, the only steps I want to keep, is step 1 and 3. So it looks like this

Configuring the build step

Ok, now that I have the steps I need, I guess it is time to configure them. There is obviously something wrong with the “Azure Web App Deployment” step considering that it is red and bold… But before I do anything about that, I need to make a change to the “Visual Studio Build” step.

As there will be some npm stuff being run, which generates that awesome, and very deep, folder structure inside of the “node_modules” folder, the “Visual Studio Build” step will unfortunately fail in its current configuration. It defines the solution to build as **/*.sln, which means “any file with an .sln-extension, in any folder”. This causes the build step to walk through _all_ the folders, including the “node_modules” folder, searching for solution files. And since the folder structure is too deep, it seems to fail if left like this. So it needs to be changed to point to the specific solution file to use. In this case, that means setting the Solution setting to Src/DeploymentDemo.sln. Like this

Configuring the deployment step

Ok, so now that the build step is set up, we need to have a look at the deployment part. Unfortunately, this is a bit more complicated than it might seem, and to be honest, than it really needed to be. At first look, it doesn’t look too bad

Ok, so all we need to do is to select the subscription to use, the Web App to deploy to and so on… That shouldn’t be too hard. Unfortunately all that becomes a bit more complicated when you open the “Azure Subscription” drop-down and realize that it is empty…

The first thing you need to do is to give VSTS access to your Azure account, which means adding a “Service Endpoint”. This is done by clicking the Manage link to the right of the drop-down, which opens a new tab where you can configure “Service Endpoints”.

The first thing to do is to click the fat, green plus sign and select Azure in the drop-down. This opens a new modal like this

There are 3 different ways to add a new connection, Credentials, Certificate Based and Service Principle Authentication. In this case, I’ll switch over to Certificate Based.

Note: If you want to use Service Principle Authentication you can find more information here

First, the connection needs a name. It can be whatever you want. It is just a name.

Next, you need to provide a bunch of information about your subscription, which is available in the publish settings file for your subscription. The easiest way to get hold of this file, is to hover over the tooltip icon, and then click the link called publish settings file included in the tool tip pop-up.

This brings you to a page where you can select what directory you want to download the publish settings for. So just select the correct directory, click “Submit”, and save the generated file to somewhere on your machine. Once that is done, you can close down the new tab and return to the “Add New Azure Connection” modal.

To get hold of the information you need, just open the newly downloaded file in a text editor. It will look similar to this

As you can see, there are a few bits of information in here. And it can be MUCH bigger than this if you have many subscriptions in the directory your have chosen. So remember to locate the correct subscription if you have more than one.

The parts that are interesting would be the attribute called Id, which needs to be inserted in the Subscription Id field in the modal, the attribute called Name, which should be inserted in Subscription Name, and finally the attribute called ManagementCertificate, which goes in the Management Certificate textbox. Like this

Once you click OK, the information will be verified, and if everything is ok, the page will reload, and you will have a new service endpoint to play with. Once that is done, you can close down the tab, and return to the build configuration set up.

The first thing you need to do here, is to click the “refresh” button to the right of the drop-down to get the new endpoint to show up. Next, you select the newly created endpoint in the drop-down.

After that, you would assume that the Web App Name drop-down would be populated with all the available web apps in your subscription. Unfortunately, this is not the case for some reason. So instead, you have to manually insert the name of the Web App you want to deploy to.

Note: You have two options when selecting the name of the Web App. Either, you choose the name of a Web App that you have already provisioned through the Azure portal, or you choose a new name, and if that name is available, the deployment script will create a new Web App for you with that name on the fly.

Next, select the correct region to deploy to, as well as any specific slot you might be deploying to. If you are deploying to the default slot, just leave the “slot” textbox empty.

The Web Deploy Package box is already populated with the value $(build.stagingDirectory)\**\*.zip which works fine for this. If you have more complicated builds, or your application contains other zips that will be output by the build, you might have to change this.

Once that is done, all you have to do is click the Save button in the top left corner, give the build definition a name, and you are done with the configuration.

Finally, click the Queue build… button to queue a new build, and in the resulting modal, just click OK. This will queue a new build, and give you a screen like this while you wait for an agent to become available

Note: Yes, I have had a failing build before I took this “screen shot”. Yours might look a little bit less red…

And as soon as there is an agent available for you, the screen will change into something like this

where you can follow along with what is happening in the build. And finally, you should be seeing something like this

At least if everything goes according to plan

Adding Gulp to the build

So far, we have managed to configure a build and deployment of our solution. However, we are still not including the Gulp task that is responsible for generating the required client-side resources. So that needs to be sorted out.

The first thing we need to do is to run

npm install

To do this, click the fat, green Add build step… button at the top of the configuration

and in the resulting modal, select Package in the left hand menu, and then add an npm build step

Next, close the modal and drag the new build step to the top of the list of steps.

By default, the command to run is set to install, which is what we need. However, we need it to run in a different directory than the root of the repository. So in the settings for the npm build step, expand the Advanced area, and update the Working Directory to say Src/DeploymentDemo.

Ok, so now npm will install all the required npm packages for us before the application is built.

Next, we need to run

bower install

To do this, add a new build step of the type Command Line from the Utility section, and drag it so that it is right after the npm step. The configuration we need for this to work is the following

Tool should be $(Build.SourcesDirectory)\Src\DeploymentDemo\node_modules\.bin\bower.cmd, the arguments should be install, and the working folder should be Src/DeploymentDemo

This will execute the bower command file, which is the same as running Bower in the command line, passing in the argument install, which will install the required bower packages. And setting the working directory will make sure it finds the bower.json file and installs the packages in the correct folder.

Now that the Bower components have been installed, or at least been configured to be installed, we can run Gulp. To do this, just add a new Gulp build step, which can be found under the Build section. And then make sure that you put it right after the Command Line step.

As our gulpfile.js isn’t in the root of the repo, the Gulp File Path needs to be changed to Src/DeploymentDemo/gulpfile.js, and the working directory once again has to be set to Src/DeploymentDemo

As I’m using the default task in this case, I don’t need to set the Gulp Task(s) to get it to run the right task.

Finally, I want to remove any left over files from the build agent as these can cause potential problems. They really shouldn’t, at least not if you are running the hosted agent, but I have run in to some weird stuff when running on my own agent, so I try to always clean up after the build. So to do this, I will run the batch file called delete_folder.bat in the Tools directory of my repo. This will use RoboCopy to safely remove deep folder structures, like the node_modules and bower_components folders.

To do this, I add two new build step to the end of the definition. Both of them of the type Batch Script from the Utility section of the Add Build Step modal.

Both of them need to have their Path set to Tools/delete_folder.bat, their Working Folder set to Src/DeploymentDemo, and their Always run checkbox checked. However, the first step needs to have the Arguments set to node_modules and the second one have it set to bower_components

This will make sure that the bower_components and node_modules folders are removed after each build.

Finally save the build configuration and you should be done! It should look something like this

However, there is still one problem. Gulp will generate new files for us, as requested, but it won’t be added to the deployment unfortunately. To solve this, we need to tell MSDeploy that we want to have those files added to the deployment. To do this, a wpp.targets-file is added to the root of the project, and checked into source control. The file is in this case called DeploymentDemo.wpp.targets and looks like this

<?xml version="1.0" encoding="utf-8" ?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  
  <Target Name="AddGulpFiles" BeforeTargets="CopyAllFilesToSingleFolderForPackage;CopyAllFilesToSingleFolderForMsdeploy">
    <Message Text="Adding gulp-generated files to deploy" Importance="high"/>
    <ItemGroup>
      <CustomFilesToInclude Include=".\dist\**\*.*" />
      <FilesForPackagingFromProject  Include="%(CustomFilesToInclude.Identity)">
        <DestinationRelativePath>.\dist\%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
      </FilesForPackagingFromProject>
    </ItemGroup>
  </Target>

</Project>

It basically tells the system that any files in the dist folder should be added to the deployment.

Note: You can read more about wpp.targets-files and how/why they work here: http://chris.59north.com/post/Integrating-a-front-end-build-pipeline-in-ASPNET-builds

That’s it! Queuing a new build, or pushing a new commit should cause the build to run, and a nice new website should be deployed to the configured location, including the resources generated by Gulp. Unfortunately, due to the npm and Bower work, the build can actually be a bit slow-ish. But it works!

Cheers!