Running ASP.NET 5 applications in Linux Containers with Docker

As a part of our ASP.NET 5 cross-platform efforts, we are actively working on making applications written in ASP.NET 5 easy to deploy and ship on Linux and Mac OS X. A while ago, we have released the first official Docker image by Microsoft: the ASP.NET 5 Preview Docker Image.

Docker is an open source project that makes it easier to run applications in sandboxed application containers on Linux. With the ASP.NET 5 Docker image, you can get a base image where the ASP.NET 5 bits are already installed to run on Linux for you. All you need to do is add your application to the image and ship it so it will run in an app container!

Hey, look at that @aspnet 5 docker image in the Docker Repository. https://t.co/hfBmVUgrwK

— The ASP.NET Team (@aspnet) November 14, 2014

In this tutorial we will show how a simple application written in ASP.NET 5 Preview can be deployed to a Linux Virtual Machine running on Microsoft Azure cloud using Docker. The tutorial can be executed on a Linux or Mac OS X machine where Docker client is installed (or you can ssh into the Linux VM you will use). Once Windows client for Docker is available, you will be able to run these commands on Windows and once Windows Server container support comes out you will be able to use Docker to manage Windows Server containers.

NOTE: Both ASP.NET 5 (vNext) and the Docker image are in preview and the following instructions are subject to change in the future. Please refer to Docker Hub page and GitHub repository for latest documentation on how to use the Docker image for ASP.NET 5.

Step 1: Create a Linux VM with Docker

As Docker only runs on Linux today, you will need a Linux machine or VM to run Docker on your server. You can find Docker installation instructions here or follow the Getting Started with Docker on Azure to get a Docker-ready Linux VM on Azure.

In this tutorial we will assume you have a Linux Virtual Machine on Azure with Docker installed. If you are using some other machine, most of this tutorial will still be relevant.

Step 2: Create a container image for your app

In order to deliver your ASP.NET application to the cloud, you will need to create a container image containing your application.

Docker container images are layers on top of each other. This means your application is an addition on top of a “base image” –in this case the base image will be microsoft/aspnet. The image layers are stored as diffs, therefore while deploying your application, your image will not contain the Linux distribution or the ASP.NET binaries; it will only contain your application, making it small in size and quickly deployable.

Creating a Docker image is done using a file called Dockerfile. Similar to a Makefile, the Dockerfile contains instructions telling Docker how to build the image.

For the sake of this tutorial, we will use the sample HelloWeb application from aspnet/Home repository on GitHub. First, clone this repository on your development machine and go to the HelloWeb directory using git:

git clone git@github.com:aspnet/Home.git aspnet-Home
cd aspnet-Home/samples/HelloWeb

In this directory you will see the following files:

├── Startup.cs
├── image.jpg
└── project.json

We are going to create a file called Dockerfile in this directory with the following contents:

FROM microsoft/aspnet

COPY . /app
WORKDIR /app
RUN ["dnu", "restore"]

EXPOSE 5004
ENTRYPOINT ["dnx", "-p", "project.json", "kestrel"]

Let’s go through this Dockerfile line by line. The first FROM line tells Docker that we will use the official ASP.NET image on Docker Hub as our base image.

The COPY line tells Docker that we will copy contents of this folder (.) to the /app directory of the container and the WORKDIR instruction will move to the /app directory.

The RUN instruction tells Docker to run the dnu restore command to install the dependencies of the application. We do this before running out application for the first time.

The EXPOSE instruction will inform Docker that this image has a service which will be listening at port 5004 (see project.json of the sample file for details). Lastly, the ENTRYPOINT instruction is the command executed to start the container and keep it up and running. In this case it is the “dnx . kestrel" command, starting the Kestrel development server for ASP.NET 5. Once executed, this process will start listening to HTTP connections coming from port 5004.

Step 3: Build the container image

Once we have Dockerfile ready, the directory should look like this, a Dockerfile residing with next to the application:

├── Dockerfile
├── Startup.cs
├── image.jpg
└── project.json

Now we will actually build the Docker image. It is very simple –just run the following Docker command in this directory:

docker build -t myapp .

This will build an image using the Dockerfile we just created and call it myapp. Every time you change your application, a new image can be built using this command. After this command finishes, we should be able to see our application in the list of Docker images on our Linux VM by running the following command on our development machine:

$ docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
myapp               latest              ccb7994d2bc1        39 seconds ago      499.8 MB
microsoft/aspnet    latest              16b1838c0b34        12 days ago         473.4 MB

As you can see, your app and the ASP.NET image are listed as images that exist on your machine.

Now we are ready to deploy our application to the cloud.

Step 4: Run the container

Running the container is the easiest part of the tutorial. Run the following Docker command on your development machine:

docker run -t -d -p 80:5004 myapp

The -t switch attaches a pseudo-tty to the container (this switch will not be necessary in future versions of ASP.NET 5).
The -d switch runs the container in the background, otherwise the web server’s standard input/output streams would be attached to our development machine’s shell.
The -p switch maps port 80 of the VM to port 5004 of the container. In this case, connections coming to port 80 of the VM will be forwarded to our container listening on port 5004.
Lastly, myapp is the Docker image name we are using to start the container. We built this image in the previous step.

Once the container is started, the following command can be used to show containers running on your machine:

$ docker ps
CONTAINER ID        IMAGE               COMMAND                CREATED              STATUS              PORTS                  NAMES
f70bd9ffbc36        myapp:latest        "/bin/sh -c 'dnx .     About a minute ago   Up About a minute   0.0.0.0:80->5004/tcp   mad_goodall

Our container has started! However, we are not quite done yet. We need to complete the endpoint port mapping for Azure VM. You need to go to the Azure Management Portal to map public TCP port 80 to internal port 80 on your Linux VM (see relevant tutorial here).

Now let’s head to the browser to see if it is working. Open http://your-cloud-service-name.cloudapp.net:80/ in your web browser:

Voila, you have an ASP.NET 5 application running on Linux inside a Docker container!

If your application is slightly different than the single-project sample application we used, you can learn more about writing Dockerfiles here and build your own images with custom commands.

Conclusion

We will continue to invest in running ASP.NET 5 applications on Linux and Docker and we are happy to bring you the Microsoft’s first official Docker image: ASP.NET 5 Preview Image.

Since this tutorial depends on previews of ASP.NET 5 and its Docker image, the exact usage instructions may change over time. Please head over to Docker Hub page or GitHub repository to see up-to-date instructions.

Please send us your feedback and help us improve this Docker image by opening new issues on GitHub repository.

Ahmet Alp Balkan (@ahmetalpbalkan)
Software Engineer, Microsoft Azure