Thursday, October 1, 2020

Building and Hosting Docker images on GitHub with GitHub Actions

Building Docker images for our ASP.NET Core websites is easy and fun. Let's see how.
Photo by Steve Johnson on Unsplash

On a previous post we discussed how to build our own Docker images from ASP.NET Core websites, push and host them on GitHub Packages. We also saw how to build and host our own NuGet packages in GitHub. Those approaches are certainly the recommended if you already have a CI/CD implemented for your project. However, for new projects running on GitHub, GitHub Actions deserves your attention.

What we will build

On this post we'll review how to build Docker images from a simple ASP.NET Core website and setup continuous integrations using GitHub Actions to automatically build, test and deploy them as GitHub Packages.

Requirements

To run this project on your machine, please make sure you have installed:

If you want to develop/extend/modify it, then I'd suggest you to also have:

About GitHub Packages

GitHub Packages is GitHub's offering for those wanting to host their own packages or Docker images. The benefits of using GitHub Packages is that it's free, you can share your images privately or publicly and you can integrate with other GitHub tooling such as APIs, Actions, webhooks and even create complex end-to-end DevOps workflows.

About GitHub Actions

GitHub Actions allows automating all your workflows such as build, test, and deployments right from GitHub. We can also use Actions to make code reviews, branch management, and issue triaging. GitHub Actions is very powerful, easy to customize, extend and it counts with lots of pre-configured templates to build and deploy pretty much everything.

Building our Docker Image

So let's quickly build our Docker image. For this demo, I'll use my own aspnet-github-actions. If you want to follow along, open a terminal and clone the project with:
git clone https://github.com/hd9/aspnet-github-actions

Building our local image

Next, cd into that folder and build a local Docker image with:
docker build . -t aspnet-gitub-actions
Now confirm your image was successfully built with:
docker images

Testing our image

With the image built, let's quickly test it by running:
docker run --rm -d -p 8080:80 --name webapp aspnet-gitthub-actions
Browse to http://localhost:8080 to confirm it's running:

Stop the container with the command below as we'll take a look at the setup on GitHub:
docker stop webapp
For more information on how to setup and run the application, check the project's README file.

Setting up Actions

With the container building and running locally, it's time to setup GitHub Actions. Open your repo and click on Actions:
From here, you can either add a blank workflow or use a build template for your project. For our simple project I can use the template Publish Docker Container:
By clicking Set up this workflow, GitHub will add a clone of that file to our repo at ~/.github/workflows/ and will load an editor so we can edit our recently created file. Go ahead and modify it to your needs. Since our Dockerfile is pretty standard, you'll only need to change the IMAGE_NAME to something adequate to your image:

Running the Workflow

As soon as you add that file, GitHub will run your first action. If you haven't pushed your code yet it'll probably fail:
To fix the error above, go ahead and push some code (or reuse mine if you wish). Assuming you have a working Dockerfile in the root of your project (where the script expects it to be), you should see your next project being queued and run. The UI is pretty cool and allows you to inspect the process in real time:
If the workflow finishes successfully, we'll get a confirmation like:
Failed again? Did you update IMAGE_NAME as explained on the previous step?

Accessing the Packages

To view your Docker images, go to the project's page and click on Packages link:
By clicking on your package, you'll see other details about your package, including how to pull it and run it locally:

Running our Packages

From there, the only thing remaining would be running our recently created packages. Since we already discussed in detail how to host and use our Docker images from GitHub packages, fell free to jump that post to learn how.

Final Thoughts

On this post we reviewed how to automatically build Docker images using GitHub Actions. GitHub Actions makes it easy to automate all your workflows including CI/CD, builds, test, and deployments. Hosting our Docker images on GitHub is valuable as you can share your images privately or with the rest of the world, integrate with GitHub tools and even create complex DevOps workflows. Other common scenarios would be building our images on GitHub and pushing them to Docker Hub or even auto-deploying them to the cloud. We'll evaluate those in the future so keep tuned!

Connect with me:

Bruno Hildenbrand      
Software Engineer and open-source enthusiast.
.NET, Go, Linux, Vim, Cloud, Architecture, Docker & Kubernetes.