Project Template: Create a Docker image for a Go application

A template project to create a Docker image for a Go application. The example application exposes an HTTP endpoint.

Tip

Java developer? Check out https://github.com/miguno/java-docker-build-tutorial

Features:

• The Docker build uses a multi-stage build setup to minimize the size of the generated Docker image, which is 5MB
• Supports Docker BuildKit
• Golang 1.22
• GitHub Actions workflows for Golang and Docker
• Optionally, uses just for running common commands conveniently, see justfile.
• Uses .env as central configuration to set variables used by justfile and other helper scripts in this project.

Requirements

Docker must be installed on your local machine. That's it. You do not need to have Go installed.

Usage and Demo

Step 1: Create the Docker image according to Dockerfile. This step builds, tests, and packages the Go application. The resulting image is 5MB in size.

# ***Creating an image may take a few minutes!***
$ docker build --build-arg PROJECT_VERSION=1.0.0-alpha -t miguno/golang-docker-build-tutorial:latest .

# You can also build with the new BuildKit.
# https://docs.docker.com/build/
$ docker buildx build --build-arg PROJECT_VERSION=1.0.0-alpha -t miguno/golang-docker-build-tutorial:latest .

Optionally, you can check the size of the generated Docker image:

$ docker images miguno/golang-docker-build-tutorial
REPOSITORY                            TAG       IMAGE ID       CREATED          SIZE
miguno/golang-docker-build-tutorial   latest    2de05b854c1b   11 minutes ago   4.78MB

Step 2: Start a container for the Docker image.

$ docker run -p 8123:8123 miguno/golang-docker-build-tutorial:latest

Step 3: Open another terminal and access the example API endpoint of the running container.

$ curl http://localhost:8123/status
{"status": "idle"}

Usage with just

If you have just installed, you can run the commands above more conveniently:

$ just
Available recipes:
    audit                   # detect known vulnerabilities (requires https://github.com/sonatype-nexus-community/nancy)
    build                   # build executable for local OS
    coverage                # show test coverage
    default                 # print available targets
    deps                    # show dependencies
    docker-image-create     # create a docker image (requires Docker)
    docker-image-run        # run the docker image (requires Docker)
    docker-image-size       # size of the docker image (requires Docker)
    evaluate                # evaluate and print all just variables
    explain lint-identifier # explain lint identifier (e.g., "SA1006")
    format                  # format source code
    lint                    # run linters (requires https://github.com/dominikh/go-tools)
    outdated                # detect outdated modules (requires https://github.com/psampaz/go-mod-outdated)
    release                 # build release executables for all supported platforms
    run                     # run executable for local OS
    send-request-to-app     # send request to the app's HTTP endpoint (requires running container)
    system-info             # print system information such as OS and architecture
    test *FLAGS             # run tests with colorized output (requires https://github.com/kyoh86/richgo)
    test-vanilla *FLAGS     # run tests (vanilla), used for CI workflow
    tidy                    # add missing module requirements for imported packages, removes requirements that aren't used anymore
    vulnerabilities         # detect known vulnerabilities (requires https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck)

Example:

$ just docker-image-create
$ just docker-image-run

Notes

You can run the Go application locally if you have Go installed. See justfile for additional commands and options.

# Build
$ go build -trimpath -ldflags="-w -s" -v -o app cmd/golang-docker-build-tutorial/main.go

# Test
$ go test -cover -v ./...

# Run
$ ./app