Building, deploying and using Docker containers
Write a multi-stage Dockerfile for a .NET app, build it for a Raspberry Pi, push it to Docker Hub and run it on any server.
Updated 1 November 20265 min read
Have you ever wanted to deploy something you built, only to find that the server doesn't have the right runtime, libraries or configuration? Running your app inside a Docker container fixes that. In this tutorial we write a Dockerfile for a .NET web API, build an image for a Raspberry Pi, push it to Docker Hub and run it on the server.
New to Docker? Start with the introduction to Docker first: it covers images, containers and the basic commands.
A quick recap
Docker recreates your environment on any machine using images and containers. An image contains everything needed to run your app: the base OS layer, the runtime, libraries and your compiled code. A container is a running instance of an image. You can run many containers from one image, and many different images side by side on the same machine.
Docker isn't magic, though: the machine still needs Docker itself. Install Docker on your development machine and on the server, and you're ready.
Writing a Dockerfile
You describe an image in a Dockerfile in your project. Here is a modern multi-stage Dockerfile for an ASP.NET Core API called MyApp.Api:
# Build stage: the .NET SDK compiles and publishes the app
FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0 AS build
ARG TARGETARCH
WORKDIR /src
# Restore first, so Docker can cache the NuGet packages
COPY MyApp.Api/MyApp.Api.csproj MyApp.Api/
RUN dotnet restore MyApp.Api/MyApp.Api.csproj -a $TARGETARCH
# Copy the rest of the source and publish a release build
COPY . .
RUN dotnet publish MyApp.Api/MyApp.Api.csproj -c Release -a $TARGETARCH --no-restore -o /app/publish
# Runtime stage: only the ASP.NET Core runtime and the published app
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
COPY --from=build /app/publish .
USER $APP_UID
EXPOSE 8080
ENTRYPOINT ["dotnet", "MyApp.Api.dll"]Let's go through it step by step:
- Two stages. The first stage (
build) uses the large .NET SDK image to compile the app. The second stage (final) starts from the much smaller ASP.NET Core runtime image and only copies in the published output. The SDK never ends up in the image you ship. - Cross-platform builds.
--platform=$BUILDPLATFORMruns the SDK natively on your machine, and-a $TARGETARCHtells .NET to compile for the target architecture (for examplearm64for a Raspberry Pi). That's much faster than emulating the whole build. - Layer caching. We copy the
.csprojand rundotnet restorebefore copying the rest of the code. As long as your dependencies don't change, Docker reuses that layer and skips the restore on the next build. - Security.
USER $APP_UIDruns the app as the non-root user that the official .NET images provide. - Port. Since .NET 8, ASP.NET Core images listen on port
8080by default, so we document that withEXPOSE 8080. - Entry point.
ENTRYPOINTis the command that runs when a container starts.
Also add a .dockerignore next to the Dockerfile with at least **/bin and **/obj, so local build output never gets copied into the image.
Build and push the image
Open a terminal in the root of your solution and build the image for a Raspberry Pi (Linux on ARM64):
docker buildx build --platform linux/arm64 -t ekozf/myapp-api:latest -f MyApp.Api/Dockerfile .--platformsets the platform the image is built for. Uselinux/amd64for a regular server, or both (linux/amd64,linux/arm64) for a multi-platform image.-ttags the image. The format is<docker-hub-user>/<name>:<tag>, so it is ready to push.-fpoints to the Dockerfile, and the final.is the build context: the folder Docker may copy files from.
See the buildx reference for every flag. Now log in and push the image to Docker Hub:
docker login
docker push ekozf/myapp-api:latestTip: add --push to the build command to build and push in one go.
Pull and run the image on the server
The image is on Docker Hub, so any machine with Docker can run it. On the server, run:
docker pull ekozf/myapp-api:latestOn Linux you may need sudo, unless your user is in the docker group. If Docker says the image doesn't exist, it is probably private: run docker login on the server too, or make the repository public in its settings on Docker Hub.
Now start a container:
docker run -d --rm -p 80:8080 --name myapp-api ekozf/myapp-api:latestThis is what each flag does:
-druns the container in the background (detached).--rmremoves the container when it stops.-p 80:8080publishes port8080of the container on port80of the host. Add an IP address (-p 192.168.1.10:80:8080) to only listen on one network interface.--name myapp-apigives the container a name, so we don't need its ID.ekozf/myapp-api:latestis the image to run.
Every docker run creates a new container from the image. You can stop, restart and delete it without affecting the image, and you can run several containers from the same image.
The :latest tag simply means "the most recent push". For anything important, push and run explicit versions such as :1.4.0, so you always know what is running and can roll back. All options are in the docker run reference.
For a service that should survive reboots, replace --rm with --restart unless-stopped.
Working with the running container
List the running containers:
docker psThis is my Raspberry Pi running three containers. The columns are:
- CONTAINER ID: the unique ID. The first few characters are enough to refer to it.
- IMAGE: the image the container was created from.
- COMMAND: the command that started the container, here the
dotnet ... .dllentry point. - CREATED and STATUS: when it was created and whether it is running.
- PORTS: the published ports.
- NAMES: the container name.
To look around inside the container, open a shell in it:
docker exec -it myapp-api bashThe official .NET images are based on Debian, so bash is available. On Alpine-based images, use sh instead. Type exit to leave. To see what your app writes to the console, use docker logs -f myapp-api.
When you are done, stop the container:
docker stop myapp-apiBecause we started it with --rm, Docker also removes the container once it stops.
Bonus: Docker Compose
Long docker run commands are easy to mistype. With Docker Compose you describe the container in a compose.yaml file instead:
services:
api:
image: ekozf/myapp-api:latest
ports:
- "80:8080"
restart: unless-stoppedStart it with docker compose up -d, follow the logs with docker compose logs -f and stop it with docker compose down. To update, run docker compose pull and then docker compose up -d again.
Conclusion
You wrote a multi-stage Dockerfile, built an image for another architecture, shipped it through Docker Hub and ran it on a server. That's the core workflow for deploying almost any app with Docker. To dig deeper, check out the official documentation. Happy shipping!
Frequently asked questions
Why does my ASP.NET Core container listen on port 8080?
Since .NET 8 the official ASP.NET Core images set port 8080 as the default HTTP port, so you publish it with -p 80:8080 to reach the app on port 80 of the host.
How do I build a Docker image for a Raspberry Pi?
Use docker buildx build --platform linux/arm64. In a .NET Dockerfile, combine --platform=$BUILDPLATFORM on the SDK stage with dotnet publish -a $TARGETARCH so the build runs natively and only the output targets ARM64.
- Docker
- .NET
- DevOps
- Raspberry Pi