golang-starter

Overview

This serves as a straightforward example illustrating how Go, Docker, Docker Hub and GitHub Actions can work seamlessly together. The ultimate goal is to achieve fully automated creation of a compact Docker image and its versioned transfer to Docker Hub.

open TODOs

there are still some open TODOs

• system view as image?
• structure oriented on https://github.com/golang-standards/project-layout
• example requests

Used technologies

• Go programming language
• Gin Web Framework features a martini-like API with performance that is very fast
• Docker as application container
• Docker Hub as container registry
• GitHub Actions to automate CD/CD workflows (build docker application, push to registry,...)
• Renovate for automatic dependency updates

Requirements

• Local Go installation to build and run application without using docker for local debugging
• Local Docker installation to build docker container from local machine
• Docker Hub account for automatically container upload to registry
• Installed Renovate GitHub App to support automatically dependency updates

In-depth explanation

How to use this example

Fork

Fork this project to your own GitHub space.

Add Docker Hub credentials

Add your personal Docker Hub credentials to your repository.

Change image name

Change IMAGE_NAME in GitHub Actions to your specific name.

Activate Renovate

Activate Renovate in your GitHub repository to support automatically dependency updates. You may have to adapt the file renovate.json to your own needs.

Start with you own stuff

The preparations have been completed. A separate Docker artifact is created for each commit. The version of the artifact is taken from the VERSION file. If you want to build a release, you simply have to adjust the number in the file.

You can now start with your own stuff.

Dockerfile

The Dockerfile outlines a two-stage process to build a Go application.

In the first phase, it creates a so-called "Builder" container based on a predefined Golang image. All of the files that comprise the Go project are copied into this container. Following that, all necessary dependencies are downloaded, tests are run, and finally the application is compiled. Special attention is paid to adjusting the build to cater to different hardware and operating system configurations.

In the second phase, a minimal executable Docker image is produced. The compiled application from the "Builder" container is copied into a new Docker image, its base being an empty ('scratch') image, alongside associated certificates. The entry point for the container is set to be the compiled application.

The resultant Docker image contains only the bare necessities to run the Go application and is therefore particularly small and efficient. It demonstrates the multilayered nature of Docker and how well-thought-out Dockerfiles can contribute to making containerization as efficient as possible.

Pipeline

GitHub Actions is used to automate two workflows:

1. go-build.yml is using a plain Go workflow to build and test this application in a fast way.
2. docker-build-and-push.yml is responsible for building the Docker image and pushing it to Docker Hub. Repository secrets DOCKER_USERNAME and DOCKER_PASSWORD are required as documented in Part How to use this example.

TODO version replacement

Where are the unit tests?

This is a simple illustration that shows the interaction between Go, Docker, Docker Hub and GitHub Actions. Although the Dockerfile contains a phase that executes the (non-existent) tests, tests were omitted for the demo due to time constraints.