Docker has become quite attractive for deployment, allowing applications to be pushed in a very portable way onto any server that can host containers. Now that ASP.NET Core is cross-platform, it can run on Linux, thus in a Docker container. Using Docker for development also is attractive and has a number of benefits including:
- Closely mirroring what gets installed on production in your development environment
- Being able to share your environment with others
- Getting an environment running very fast
- Being able to extend your environment very fast and easily (i.e. adding a Redis server)
- Not polluting your machine with frameworks since they are installed in the containers
In this article, we’re going to walk through setting up a development environment for ASP.NET Core using Docker. Then we’ll walk through the developer workflow with these technologies.
If you are new to Docker and ASP.NET Core, check out my article on Getting Started with Docker and ASP.NET Core on OS X (there isn’t much that is OS X-specific). We’re going to assume you have Docker installed and running (you can type the docker command on in your terminal), and you have a basic understanding of running Docker containers.
Setting up the Environment
One of the niceties of Docker is you don’t have to do the step of setting up the stack you want to use, in this case ASP.NET Core. You can simply run an image that has it already installed, such as this ASP.NET Core development environment image. We’re going to go ahead and build an image for development ourselves though, so you know how to do it and can customize it for your project. You don’t even need the stack you want to build into a container installed locally.
Building the ASP.NET Core Container with a Dockerfile
Docker uses a file called Dockerfile (with no extension) by default, for specifying what the container should contain. Microsoft provides several flavors of images to start with that already have .NET Core installed, so we will start with that and don’t need to worry about installing the .NET Core framework and SDK. They are publically available here on Docker Hub. You can always look at the Dockerfile’s for these images if you want to know how .NET Core is installed in the container, or you can always create your own if you need a custom installation of .NET Core, for instance.
Microsoft provides a few flavors, such as an image with the SDK installed, and a minimal image without the SDK which is good for production deployment. We are going to go with the image Microsoft created for development, microsoft/dotnet:1.0.0-preview2-sdk, which has the SDK installed (as of this writing, the main image, microsoft/dotnet:latest, also has in the SDK installed so I am not sure how their currently differ).
We are going to layer configuration on top of their image to make an ASP.NET Core development environment. Let’s get started.
In an empty directory, create a file with no extension (this is just the default convention) named Dockerfile and put the follow code inside:
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
# base image
FROM microsoft/dotnet:1.0.0-preview2-sdk
# set up package cache
RUN curl -o /tmp/packagescache.tar.gz
&& \
mkdir /packagescache && cd /packagescache && \
tar xvf /tmp/packagescache.tar.gz && \
rm /tmp/packagescache.tar.gz && \
cd /
# set env var for packages cache
ENV DOTNET_HOSTING_OPTIMIZATION_CACHE /packagescache
# set up network
EXPOSE 5000/tcp
ENV ASPNETCORE_URLS https://*:5000[/pcsh]
There are four sections in this file, noted with comments. The first part specifies which image to start with. The second and third create a cache in the container of ASP.NET Core packages so dependencies are fast to resolve when adding them to your project. The last part lets your web app become exposed on port 5000 of the container.
With this file in place, you are ready to build a Docker image. To do that, run this command:
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
docker build -t <yourTag:YourAspNetImageName> .
[/pcsh]
The –t allows you to name your image, and the period means, look for the Dockerfile in the current directory. Now, type this to see your created image:
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
docker images[/pcsh]
You should see your image listed, which means it’s ready to have containers created from it in which you can compile and run your ASP.NET Core app.
Using the Container for Development
To create a container from the image, run this command:
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
docker run -i -p 80:5000 -v $(pwd):/app /w /app -t <yourTag:YourAspNetImageName>[/pcsh]
Let’s break down what this is doing:
- -i says to run it interactively, so you will be put into the container’s bash after it starts. We could use –d to have it run in the background, then log into the container for build, etc. tasks.
- -p is to map the container’s port (5000) to the host computer’s port (80).
- -v allows you to mount a folder on the host into the container, so in this case we’re mapping our current directory to the container’s ‘/app’ directory so we can access our source code in the container in order to compile and run.
- -w sets the container’s working directory to where the source code is located
- -t is to specify the image to create the container from
After running the run command above, you should be in the container’s bash, in the /app directory which is mapped to the directory you were in when you ran the container. You can now create an ASP.NET Core app however you please, such as typing dotnet net –t Web in the container, or creating or cloning one on your host computer. You run your .NET CLI tasks in the container, and do everything else outside of it in your favorite IDE.
To enhance the development workflow, add dotnet watch to your ASP.NET Core app, in order to have the container automatically rebuild and run the app when you save source code changes,
- Add DotNet.Watcher.Tools to the tools section of your app’s project.json file:[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
"tools": { "Microsoft.DotNet.Watcher.Tools": "1.0.0-preview2-final" },[/pcsh]
- Run dotnet restore
- Now you will be able to run this in your container:
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
dotnet watch run [/pcsh]
This will run the application with the watch enabled. Now you’re in a great spot to build something in your app, save the changes, and try it out at https://localhost:5000.
You can type exit to leave the container. Note, the container will shut down, because you used the –i flag when running it (as opposed to –d to have it stay running in the background).
Cleanup
You’re going to want to do a little cleanup regularly, to delete unused images and containers. You can end up with quite a lot of containers (each run command creates one) and images (i.e building several while building the image). Key operations for this are as follows.
Listing the containers:
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
docker ps –a[/pcsh]
Deleting all containers
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
docker rm $(docker ps –a –q)[/pcsh]
Deleting an image:
[pcsh lang=”csharp” tab_size=”4″ message=”” hl_lines=”” provider=”manual”]
docker rmi <image name>[/pcsh]
You can add an –f flag after rm or rmi to force delete if the container is running or the image is in use.
Next Steps
You now have the basics set up for doing ASP.NET Core development using a Docker container to build and run the application. As you go along, you will likely need additional components, such as a database server, which you should run in another container. Docker Compose can help you do this quite easily. Check out this ASP.NET Core sample app with a docker-compose file that specifies to create the ASP.NET Core container, but also a container with PostgreSQL. The official Postgres image is used from Docker Hub, so no Dockerfile is needed for that one.
You can share your image by using docker push to get it into Docker Hub or a private image repository. You’ll soon want to learn how to debug an ASP.NET Core app in a container.
Here is an ASP.NET Core image you can take a look out and run if you’d like.