docker_setting_asp

Docker - Containerizing ASP.NET Core Applications

ASP.NET Core is Microsoft’s modern, cross-platform framework for building web applications and services. Docker provides an excellent way to package, deploy, and run these applications consistently across different environments.

This tutorial guides you through containerizing a simple ASP.NET Core application using Docker, following current best practices.

Prerequisites

Before you begin, ensure you have the following installed:

• Docker Desktop: For Windows and macOS users. It handles the underlying virtualization and provides the Docker engine and CLI tools. Download from the official Docker website.
• Docker Engine: For Linux users. Follow the official installation guide for your specific distribution.
• .NET SDK: You need the .NET Software Development Kit (SDK) to create and build ASP.NET Core applications. Choose the latest stable version (e.g., .NET 6, .NET 7, .NET 8 or later). Download from the official .NET website.

Verify your Docker installation by opening a terminal or command prompt and running:

docker --version

And verify your .NET SDK installation by running:

dotnet --version

Creating a Sample ASP.NET Core Application

Let’s start by creating a basic ASP.NET Core web application using the .NET CLI.

Step 1: Open your terminal or command prompt.

Step 2: Create a new directory for your project and navigate into it.

mkdir MyWebApp
cd MyWebApp

Step 3: Create a new ASP.NET Core Web App using the dotnet new command.

dotnet new webapp

This command creates a simple web application project in the current directory, including sample pages and configuration.

Adding a Dockerfile

A Dockerfile is a text file containing instructions for building a Docker image. We’ll create one for our ASP.NET Core application using a multi-stage build approach, which is a best practice for optimizing image size and security.

Step 1: In the root of your MyWebApp directory (where the .csproj file is located), create a new file named Dockerfile (no extension).

Step 2: Add the following content to the Dockerfile. Adjust the .NET version (e.g., 8.0) if you used a different SDK version.

# Stage 1: Build the application
# Use the official .NET SDK image as the base image for building
# Choose the SDK version matching your project's target framework
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build-env
WORKDIR /app

# Copy the project file and restore dependencies
COPY *.csproj ./
RUN dotnet restore

# Copy the rest of the application code
COPY . .

# Publish the application, ensuring it's optimized for release
# Use a specific runtime identifier if needed, e.g., linux-x64
RUN dotnet publish -c Release -o out

# Stage 2: Create the runtime image
# Use the official ASP.NET Core runtime image as the base
# Choose the runtime version matching your project's target framework
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app

# Copy the published output from the build stage
COPY --from=build-env /app/out .

# Expose the port the application will run on (default is 8080 for .NET 8+)
# Check Properties/launchSettings.json or appsettings.json if unsure
EXPOSE 8080

# Set the entry point for the container
ENTRYPOINT ["dotnet", "MyWebApp.dll"]

Explanation of the Dockerfile:

• Multi-Stage Build: We use two FROM instructions. The first stage (build-env) uses the full .NET SDK to build the application. The second stage uses the leaner ASP.NET Core runtime image, copying only the necessary published artifacts. This significantly reduces the final image size.
• FROM ... AS build-env: Defines the build stage using the .NET SDK image.
• WORKDIR /app: Sets the working directory inside the container.
• COPY *.csproj ./ and RUN dotnet restore: Copies the project file first and restores dependencies. This leverages Docker’s layer caching effectively.
• COPY . .: Copies the rest of the source code.
• RUN dotnet publish -c Release -o out: Builds and publishes the application for release configuration into the out directory.
• FROM mcr.microsoft.com/dotnet/aspnet...: Defines the final runtime stage using the ASP.NET runtime image.
• COPY --from=build-env /app/out .: Copies only the published application from the build stage.
• EXPOSE 8080: Informs Docker that the container listens on port 8080 (Note: Kestrel’s default port changed to 8080 in .NET 8. For .NET 6/7 it might be 80). This doesn’t publish the port; it’s documentation.
• ENTRYPOINT ["dotnet", "MyWebApp.dll"]: Specifies the command to run when the container starts.

Step 3: (Optional but recommended) Create a .dockerignore file in the same directory as the Dockerfile. This file tells Docker which files and directories to exclude from the build context, speeding up the build and reducing image size. Add the following lines:

bin/
obj/
Dockerfile
.dockerignore
*.vs
*.vscode
.git
README.md

Building the Docker Image

Now, let’s build the Docker image using the Dockerfile.

Step 1: Ensure you are in the MyWebApp directory in your terminal.

Step 2: Run the docker build command:

# The -t flag tags the image with a name (e.g., my-aspnet-app)
# The . indicates the build context (the current directory)
docker build -t my-aspnet-app .

Docker will execute the instructions in your Dockerfile, download base images if needed, and create your application image. This might take a few minutes the first time.

Running the Docker Container

With the image built, we can now run it as a container.

Step 1: Run the docker run command:

# -d: Run the container in detached mode (in the background)
# -p 8081:8080: Map port 8081 on the host to port 8080 in the container
#    (Use the port exposed in your Dockerfile, e.g., 8080 for .NET 8+)
# --name my-running-app: Assign a name to the container for easy reference
# my-aspnet-app: The name of the image to use
docker run -d -p 8081:8080 --name my-running-app my-aspnet-app

You can check if the container is running using docker ps:

docker ps

This command will list all running containers, including my-running-app.

Accessing the Application

Since we mapped the container’s port 8080 to the host’s port 8081 (-p 8081:8080), you can access your running ASP.NET Core application by opening a web browser and navigating to:

http://localhost:8081

You should see the default ASP.NET Core welcome page.

Stopping and Removing the Container

To stop the container:

docker stop my-running-app

To remove the stopped container:

docker rm my-running-app

Further Learning

This tutorial covered the basics of containerizing an ASP.NET Core application. Here are some areas for further exploration:

• Configuration: Learn how to pass configuration to your application using environment variables (-e flag in docker run) or volume mounts.
• HTTPS: Configure your application and Docker setup to handle HTTPS traffic, often involving reverse proxies.
• Docker Compose: Use Docker Compose to define and run multi-container applications (e.g., your web app plus a database).
• Windows Containers: If you need to run older ASP.NET applications based on the full .NET Framework, you’ll need to use Windows Containers, which require Windows hosts and different base images (e.g., mcr.microsoft.com/dotnet/framework/aspnet).
• Container Registries: Push your custom images to registries like Docker Hub or Azure Container Registry (ACR) to share and deploy them.
• Official Documentation: Refer to the official Docker and .NET documentation for more in-depth information.