Building, Running, and Testing .NET Core and ASP.NET Core 2.1 in Docker on a Raspberry Pi (ARM32)
I love me some Raspberry Pi. They are great little learning machines and are super fun for kids to play with. Even if those kids are adults and they build a 6 node Kubernetes Raspberry Pi Cluster.
Open source .NET Core runs basically everywhere - Windows, Mac, and a dozen Linuxes. However, there is an SDK (that compiles and builds) and a Runtime (that does the actual running of your app). In the past, the .NET Core SDK (to be clear, the ability to "dotnet build") wasn't supported on ARMv7/ARMv8 chips like the Raspberry Pi. Now it is.
.NET Core is now supported on Linux ARM32 distros, like Raspbian and Ubuntu!
Note: .NET Core 2.1 is supported on Raspberry Pi 2+. It isn’t supported on the Pi Zero or other devices that use an ARMv6 chip. .NET Core requires ARMv7 or ARMv8 chips, like the ARM Cortex-A53. Folks on the Azure IoT Edge team use the .NET Core Bionic ARM32 Docker images to support developers writing C# with Edge devices.
There's two ways to run .NET Core on a Raspberry Pi.
One, use Docker. This is literally the fastest and easiest way to get .NET Core up and running on a Pi. It sounds crazy but Raspberry Pis are brilliant little Docker container capable systems. You can do it in minutes, truly. You can install Docker quickly on a Raspberry Pi with just:
curl -sSL https://get.docker.com | sh
sudo usermod -aG docker pi
After installing Docker you'll want to log in and out. You might want to try a quick sample to make sure .NET Core runs! You can explore the available Docker tags at https://hub.docker.com/r/microsoft/dotnet/tags/ and you can read about the .NET Core Docker samples here https://github.com/dotnet/dotnet-docker/tree/master/samples/dotnetapp
Now I can just docker run and then pass in "dotnet --info" to find out about dotnet on my Pi.
pi@raspberrypi:~ $ docker run --rm -it microsoft/dotnet:2.1-sdk dotnet --info
.NET Core SDK (reflecting any global.json):
Version: 2.1.300-rc1-008673
Commit: f5e3ddbe73
Runtime Environment:
OS Name: debian
OS Version: 9
OS Platform: Linux
RID: debian.9-x86
Base Path: /usr/share/dotnet/sdk/2.1.300-rc1-008673/
Host (useful for support):
Version: 2.1.0-rc1
Commit: eb9bc92051
.NET Core SDKs installed:
2.1.300-rc1-008673 [/usr/share/dotnet/sdk]
.NET Core runtimes installed:
Microsoft.NETCore.App 2.1.0-rc1 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
To install additional .NET Core runtimes or SDKs:
https://aka.ms/dotnet-download
This is super cool. There I'm on the Raspberry Pi (RPi) and I just ask for the dotnet:2.1-sdk and because they are using "multiarch" docker files, Docker does the right thing and it just works. If you want to use .NET Core on ARM32 with Docker, you can use any of the following tags.
Note: The first three tags are multi-arch and bionic is Ubuntu 18.04. The codename stretch is Debian 9. So I'm using 2.1-sdk and it's working on my RPi, but I can be specific if I'd prefer.
- 2.1-sdk
- 2.1-runtime
- 2.1-aspnetcore-runtime
- 2.1-sdk-stretch-arm32v7
- 2.1-runtime-stretch-slim-arm32v7
- 2.1-aspnetcore-runtime-stretch-slim-arm32v7
- 2.1-sdk-bionic-arm32v7
- 2.1-runtime-bionic-arm32v7
- 2.1-aspnetcore-runtime-bionic-arm32v7
Try one in minutes like this:
docker run --rm microsoft/dotnet-samples:dotnetapp
Here it is downloading the images...
In previous versions of .NET Core's Dockerfiles it would fail if you were running an x64 image on ARM:
standard_init_linux.go:190: exec user process caused "exec format error"
Different processors! But with multiarch per https://github.com/dotnet/announcements/issues/14 Kendra from Microsoft it just works with 2.1.
Docker has a multi-arch feature that microsoft/dotnet-nightly recently started utilizing. The plan is to port this to the official microsoft/dotnet repo shortly. The multi-arch feature allows a single tag to be used across multiple machine configurations. Without this feature each architecture/OS/platform requires a unique tag. For example, the microsoft/dotnet:1.0-runtime tag is based on Debian and microsoft/dotnet:1.0-runtime-nanoserver if based on Nano Server. With multi-arch there will be one common microsoft/dotnet:1.0-runtime tag. If you pull that tag from a Linux container environment you will get the Debian based image whereas if you pull that tag from a Windows container environment you will get the Nano Server based image. This helps provide tag uniformity across Docker environments thus eliminating confusion.
In these examples above I can:
- Run a preconfigured app within a Docker image like:
- docker run --rm microsoft/dotnet-samples:dotnetapp
- Run dotnet commands within the SDK image like:
- docker run --rm -it microsoft/dotnet:2.1-sdk dotnet --info
- Run an interactive terminal within the SDK image like:
- docker run --rm -it microsoft/dotnet:2.1-sdk
As a quick example, here I'll jump into a container and new up a quick console app and run it, just to prove I can. This work will be thrown away when I exit the container.
pi@raspberrypi:~ $ docker run --rm -it microsoft/dotnet:2.1-sdk
root@063f3c50c88a:/# ls
bin boot dev etc home lib media mnt opt proc root run sbin srv sys tmp usr var
root@063f3c50c88a:/# cd ~
root@063f3c50c88a:~# mkdir mytest
root@063f3c50c88a:~# cd mytest/
root@063f3c50c88a:~/mytest# dotnet new console
The template "Console Application" was created successfully.
Processing post-creation actions...
Running 'dotnet restore' on /root/mytest/mytest.csproj...
Restoring packages for /root/mytest/mytest.csproj...
Installing Microsoft.NETCore.DotNetAppHost 2.1.0-rc1.
Installing Microsoft.NETCore.DotNetHostResolver 2.1.0-rc1.
Installing NETStandard.Library 2.0.3.
Installing Microsoft.NETCore.DotNetHostPolicy 2.1.0-rc1.
Installing Microsoft.NETCore.App 2.1.0-rc1.
Installing Microsoft.NETCore.Platforms 2.1.0-rc1.
Installing Microsoft.NETCore.Targets 2.1.0-rc1.
Generating MSBuild file /root/mytest/obj/mytest.csproj.nuget.g.props.
Generating MSBuild file /root/mytest/obj/mytest.csproj.nuget.g.targets.
Restore completed in 15.8 sec for /root/mytest/mytest.csproj.
Restore succeeded.
root@063f3c50c88a:~/mytest# dotnet run
Hello World!
root@063f3c50c88a:~/mytest# dotnet exec bin/Debug/netcoreapp2.1/mytest.dll
Hello World!
If you try it yourself, you'll note that "dotnet run" isn't very fast. That's because it does a restore, build, and run. Compilation isn't super quick on these tiny devices. You'll want to do as little work as possible. Rather than a "dotnet run" all the time, I'll do a "dotnet build" then a "dotnet exec" which is very fast.
If you're doing to do Docker and .NET Core, I can't stress enough how useful the resources are over at https://github.com/dotnet/dotnet-docker.
Building .NET Core Apps with Docker
- .NET Core Docker Sample - This sample builds, tests, and runs the sample. It includes and builds multiple projects.
- ASP.NET Core Docker Sample - This sample demonstrates using Docker with an ASP.NET Core Web App.
Develop .NET Core Apps in a Container
- Develop .NET Core Applications - This sample shows how to develop, build and test .NET Core applications with Docker without the need to install the .NET Core SDK.
- Develop ASP.NET Core Applications - This sample shows how to develop and test ASP.NET Core applications with Docker without the need to install the .NET Core SDK.
Optimizing Container Size
- .NET Core Alpine Docker Sample - This sample builds, tests, and runs an application using Alpine.
- .NET Core self-contained Sample - This sample builds and runs an application as a self-contained application.
ARM32 / Raspberry Pi
- .NET Core ARM32 Docker Sample - This sample builds and runs an application with Debian on ARM32 (works on Raspberry Pi).
- ASP.NET Core ARM32 Docker Sample - This sample builds and runs an ASP.NET Core application with Debian on ARM32 (works on Raspberry Pi).
I found the samples to be super useful...be sure to dig into the Dockerfiles themselves as it'll give you a ton of insight into how to structure your own files. Being able to do Multistage Dockerfiles is crucial when building on a small device like a RPi. You want to do as little work as possible and let Docker cache as many layers with its internal "smarts." If you're not thoughtful about this, you'll end up wasting 10x the time building image layers every build.
Dockerizing a real ASP.NET Core Site with tests!
Can I take my podcast site and Dockerize it and build/test/run it on a Raspberry Pi? YES.
FROM microsoft/dotnet:2.1-sdk AS build
WORKDIR /app
# copy csproj and restore as distinct layers
COPY *.sln .
COPY hanselminutes.core/*.csproj ./hanselminutes.core/
COPY hanselminutes.core.tests/*.csproj ./hanselminutes.core.tests/
RUN dotnet restore
# copy everything else and build app
COPY . .
WORKDIR /app/hanselminutes.core
RUN dotnet build
FROM build AS testrunner
WORKDIR /app/hanselminutes.core.tests
ENTRYPOINT ["dotnet", "test", "--logger:trx"]
FROM build AS test
WORKDIR /app/hanselminutes.core.tests
RUN dotnet test
FROM build AS publish
WORKDIR /app/hanselminutes.core
RUN dotnet publish -c Release -o out
FROM microsoft/dotnet:2.1-aspnetcore-runtime AS runtime
WORKDIR /app
COPY --from=publish /app/hanselminutes.core/out ./
ENTRYPOINT ["dotnet", "hanselminutes.core.dll"]
Love it. Now I can "docker build ." on my Raspberry Pi. It will restore, test, and build. If the tests fail, the Docker build will fail.
See how there's an extra section up there called "testrunner" and then after it is "test?" That testrunner section is a no-op. It sets an ENTRYPOINT but it is never used...yet. The ENTRYPOINT is an implicit run if it is the last line in the Dockerfile. That's there so I can "Run up to it" if I want to.
I can just build and run like this:
docker build -t podcast .
docker run --rm -it -p 8000:80 podcast
NOTE/GOTCHA: Note that the "runtime" image is microsoft/dotnet:2.1-aspnetcore-runtime, not microsoft/dotnet:2.1-runtime. That aspnetcore one pre-includes the binaries I need for running an ASP.NET app, that way I can just include a single reference to "<PackageReference Include="Microsoft.AspNetCore.App" Version="2.1.0-rc1-final" />" in my csproj. If didn't use the aspnetcore-runtime base image, I'd need to manually pull in all the ASP.NET Core packages that I want. Using the base image might make the resulting image files larger, but it's a balance between convenience and size. It's up to you. You can manually include just the packages you need, or pull in the "Microsoft.AspNetCore.App" meta-package for convenience. My resulting "podcast" image ended up 205megs, so not to bad, but of course if I wanted I could trim in a number of ways.
Or, if I JUST want test results from Docker, I can do this! That means I can run the tests in the Docker container, mount a volume between the Linux container and (theoretical) Window host, and then open the .trx resulting file in Visual Studio!
docker build --pull --target testrunner -t podcast:test .
docker run --rm -v D:\github\hanselminutes-core\TestResults:/app/hanselminutes.core.tests/TestResults podcast:test
Check it out! These are the test results from the tests that ran within the Linux Container:
Here's the result. I've now got my Podcast website running in Docker on an ARM32 Raspberry Pi 3 with just an hours' work (writing the Dockerfile)!
Second - did you make it this far down? - You can just install the .NET Core 2.1 SDK "on the metal." No Docker, just get the tar.gz and set it up. Looking at the RPi ARM32v7 Dockerfile, I can install it on the metal like this. Note I'm getting the .NET Core SDK *and* the ASP.NET Core shared runtime. In the final release build you will just get the SDK and it'll include everything, including ASP.NET.
$ sudo apt-get -y update
$ sudo apt-get -y install libunwind8 gettext
$ wget https://dotnetcli.blob.core.windows.net/dotnet/Sdk/2.1.300-rc1-008673/dotnet-sdk-2.1.300-rc1-008673-linux-arm.tar.gz
$ wget https://dotnetcli.blob.core.windows.net/dotnet/aspnetcore/Runtime/2.1.0-rc1-final/aspnetcore-runtime-2.1.0-rc1-final-linux-arm.tar.gz
$ sudo mkdir /opt/dotnet
$ sudo tar -xvf dotnet-sdk-2.1.300-rc1-008673-linux-arm.tar.gz -C /opt/dotnet/
$ sudo tar -xvf aspnetcore-runtime-2.1.0-rc1-final-linux-arm.tar.gz -C /opt/dotnet/
$ sudo ln -s /opt/dotnet/dotnet /usr/local/bin
$ dotnet --info
Cross-platform for the win!
Sponsor: Check out JetBrains Rider: a cross-platform .NET IDE. Edit, refactor, test and debug ASP.NET, .NET Framework, .NET Core, Xamarin or Unity applications. Learn more and download a 30-day trial!
About Scott
Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.
About Newsletter
How is this faster and easier than just untaring the binaries, especially if you've never used docker before?
Browsing the net for examples, tutorials have a feeling Win10 much less supported on Raspberry, but I would rather stay with Windows.
Is Win10 that much worse? Slower? Larger footprint? Full of bugs? Not supported? So what I am really missing if I insist on Win10 on Raspberry? ...except the much less examples.
I'm curious if you notice a performance difference between running it on docker vs running it on the metal. i.e. dotnet build times, test run times?
I'll eventually build a new one on x86_64 and move my stuff over, but it's a heavy lift with all the crap I accumulated on there over the years.
I'm looking forward to playing with this.
How is this faster and easier than just untaring the binaries, especially if you've never used docker before?
The crucial assumption is that you have used docker before; you can then lean on your knowledge about docker, it being the same across all platforms.
If you have not used docker then of course it's not easier.
.NET Core requires ARMv7 or ARMv8 chips, like the ARM Cortex-A53.
I see that RPI, it's the main attraction. I'm curious, does it mean that will work for Parallella board as well?
What about Intel Galileo?
Thanks for great article.. This helped me a lot. One small correction i found in second option.
The command
$ sudo tar -xvf dotnet-sdk-latest-linux-arm.tar.gz -C /opt/dotnet/
should be changed to
sudo tar -xvf dotnet-sdk-2.1.300-rc1-008673-linux-arm.tar.gz -C /opt/dotnet/
Thanks,
Jeeva
It doesn't support it, and there is also another related ticket - https://github.com/moby/moby/issues/16079 to allow copying file from image without starting it.
Typically right now you need to do some hacks if you don't want to include test results into final image:
1. You need to specify some label for docker build stage that is doing test run
2. Then after build is completed you can make bash script that find image id by that label like this
imageId=$(docker images --filter "label=someBuildImage" --filter "dangling=true" -q)`
3. then, as we can't get file from volume, you need to create container without running it, copying file from that container to build agent host, and finally remove container like this
id=$(docker create $imageId)
docker cp $id:/tmp/test_results.xml $(System.DefaultWorkingDirectory)/test_results.xml
docker rm -v $id
4. and then you can use that file in other build steps
Yeah, it stinks. Otherway is just to put it to final image, but as for me it stinks less :)
This definitively needs a GUI.
Comments are closed.
I'm looking at a CI setup where the build produces the final image for deployment, but also outputs the test results without having to run the tests more than once, or do any redundant building (and without including test assemblies in the final image). If any tests fail, the build fails, but the test results should still be available.
Or, is this not possible because mounting to a host folder can only be done with the docker run command?
If that's the case, it may be possible to copy the test results file alone into the final image, from which it can be extracted afterward, but then this approach would only work if the build actually completes.