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!
— 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 firstname.lastname@example.org: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 ["kpm", "restore"] EXPOSE 5004 ENTRYPOINT ["k", "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.
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
RUN instruction tells Docker to run the
kpm restore command to install the dependencies of the application. We do this before running out application for the first time.
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
k kestrelcommand, 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
-tswitch attaches a pseudo-tty to the container (this switch will not be necessary in future versions of ASP.NET 5).
-dswitch runs the container in the background, otherwise the web server’s standard input/output streams would be attached to our development machine’s shell.
-pswitch 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.
myappis 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 'k kestr 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.
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.