Hosting our own Docker images on GitHub is simpler than you think. On this post, let's review how.
Photo by Annie Spratt on Unsplash |
We recently reviewed how to host our NuGet packages on GitHub. Turns out that
another popular feature of
GitHub Packages
is hosting Docker images. Given that GitHub is the world's largest development
website and you're probably already hosting your code up there, why not also
review how to build, host and consume our own ASP.NET Core Docker images on
it?
On this post we will:
- Build an run our Docker image using ASP.NET Core
- Push our custom images to GitHub Packages
-
Pull and test our package from a different machine (my very own
Alpine Linux VM
on this case)
Requirements
To run this project on your machine, please make sure you have installed:
- Docker Desktop (Mac, Windows) or Docker Engine (Linux)
- Docker Compose
- .NET SDK 3.1
- A git client
- A Linux shell or WSL
If you want to develop/extend/modify it, then I'd suggest you to also have:
- a valid GitHub account
- Visual Studio 2019
- (or) Visual Studio Code
About GitHub Packages
Building our Docker Image
So let's quickly build our Docker image. For this demo, I'll use my own
aspnet-docker project. If you want to follow
along, open a terminal and clone the project with:
git clone https://github.com/hd9/aspnet-docker
Building our local image
Next, cd into that folder and build a local Docker image with:
docker build . -t webapp:0.0.1
Now confirm your image was successfully built with:
docker images
You should see something along the lines of:
webapp
0.0.1
73a91c1204db 21 seconds
ago 212MB
For more information on how to setup and run the application, check
the
project's README file.
Testing our local image
docker run --rm -d -p 8080:80 webapp:0.0.1
Test it at
http://localhost:8080/. Here's what you should see:
Pushing packages to GitHub
With the image ready and working, let's review
how to push your own Docker images to GitHub.
Generating an API Key
In order to authenticate to GitHub Packages the first thing we'll need
is an access token. Open your GitHub account, go to Settings ->
Developer Settings ->
Personal access tokens, click Generate new Token, give it a name, select
write:packages and save:
Now copy the API key provided, we'll use it in the next step.
Logging in with Docker
To push our images to GitHub, first we log in with:
docker login https://docker.pkg.github.com -u <github-username> -p
<api-key>
Or, you could echo your api key from a file with:
cat api-key.txt |
docker login https://docker.pkg.github.com -u <github-username>
--password-stdin
Or even better, using an env var with:
echo $<envvar-name> | docker login https://docker.pkg.github.com -u
<github-username> --password-stdin
Tagging our image
With the login successful, we now need to tag the image and push. Let's
tag it first with:
docker tag <img-name>
docker.pkg.github.com/<gh-user>/<repo>/<img-name>:<version>
Confirm you get both images with docker image ls:
docker image ls
Here's what you should see:
REPOSITORY
TAG IMAGE
ID
CREATED
SIZE
webapp 0.0.1 73a91c1204db 30 minutes ago 212MB
docker.pkg.github.com/hd9/aspnet-docker/webapp 0.0.1 73a91c1204db 30 minutes ago 212MB
webapp 0.0.1 73a91c1204db 30 minutes ago 212MB
docker.pkg.github.com/hd9/aspnet-docker/webapp 0.0.1 73a91c1204db 30 minutes ago 212MB
Pushing the image to GitHub
Finally, push it to the remote repo with:
docker push
docker.pkg.github.com/<gh-user>/<repo>/<img-name>:<version>
Here's what I got during my tests:
Reviewing our image on GitHub
Let's confirm our image was successfully pushed to GitHub. Open your
project's page and click on Packages. Our
webapp package
looks like this:
Using our image
To consume our image we'll have to (1) login with docker, (2) pull the
image and (3) run it. As previously mentioned, I'll run it from a
different box. This time on an
Alpine Linux VM
I love playing with.
To learn how to install and run Docker on Alpine,
check this link.
Let's once more login on GitHub with Docker with:
docker login https://docker.pkg.github.com -u <github-username> -p
<api-key>
Pulling the image the image
After the login, pulling our image is as simple as:
docker pull
docker.pkg.github.com/<gh-user>/<repo>/<img-name>:<version>
For context, here's my pull in action:
After the pull confirm with docker image ls:
Run the image
And finally run our image with:
docker run --rm -d -p 8080:80 webapp:0.0.1
If you want, confirm your image is running with:
docker ps
Accessing the container
Lastly, let's confirm we can access it from our host. On Alpine, enter
ip a show eth0 to show the
VM's internal IP:
And finally, access it from the host (your machine) with your browser. On
my case,
http://172.27.197.46:8080/:
Final Thoughts
Source Code
As always, the source code is available on GitHub.
References
See Also
- Microservices in ASP.NET
- My journey to 1 million articles read
- Building and Hosting Docker images on GitHub with GitHub Actions
- Creating ASP.NET Core websites with Docker
- Hosting NuGet packages on GitHub
- Adding Application Insights telemetry to your ASP.NET Core website
- Deploying Docker images to Azure App Services
- How to push Docker images to ACR - Azure Container Registry
- Send emails from ASP.NET Core websites using SendGrid and Azure
- Monitor ASP.NET applications using Application Insights and Azure Alerts
- Distributed caching in ASP.NET Core using Redis, MongoDB and Docker
- How to build and run ASP.NET Core apps on Linux