Project challenges / verified progress
Engineering project paths

The engineering notebook

Beacon: package it so anyone can run it

You can build a small OCI image for a Go service, run it as non-root with durable local state, stamp and publish it by digest, generate an SBOM, scan and triage findings, sign the image, and run the complete local stack with Docker Compose.

Before you begin

Prerequisites and setup

Prior knowledge: Basic command-line use and familiarity with the supplied Go service are helpful. Container concepts, image building, security scanning, and signing are taught in the course.

Tools, accounts, and cost: Docker Engine 25+ with Docker Compose v2, or a compatible Podman/Colima setup; Go 1.22+; and a GitLab project with Container Registry enabled. Check the current registry storage limits for your GitLab plan; no cloud provider account is required.

Required course tool
Docker Engine 25+
Installation guide
Check it with docker version.
Starting project
At this tag you already have the finished Beacon service from course 2: a Go binary at `cmd/beacond` that schedules checks, stores results in SQLite, serves a JSON API on `:7427`, logs with `slog`, exposes `/healthz` and `/readyz`, and shuts down gracefully on `SIGTERM`.
Estimated study time
about 15 hr across 9 stages.
Estimate sums each stage’s reading, implementation, and debugging time; your pace will vary.
Entry point
You may start here without completing earlier Vault paths. This prepared project snapshot includes the code described above; the listed knowledge, tools, and any cost notes still apply.

Your learning trail

0 / 9 complete

A verified submission confirms the project runs and prints the expected output. It does not grade code quality or award a credential. Course progress is saved in this browser, so it does not automatically transfer to another device.

System design

What you are building

The containerized Beacon path starts with the kernel model, builds a naive image, shrinks it with a multi-stage runtime, removes root privileges, stamps the artifact with OCI metadata, publishes it to GitLab Container Registry, inventories and scans it, signs the pushed digest, and finally runs the service locally with Compose, a health check, and a named SQLite volume.

BEACON / THE ARTIFACTYour sourcethe service from course twoTHE BUILD YOU OWNBuild stagestatic binary, no cgoRuntime imagenon-root, ~15MBSBOM and scanknow what is insideSignatureproof it came from youOUTSIDE YOUR LAPTOPRegistryOCI images, tags and digestsAnyone pulling itcan verify the signaturea tag can move; a digest is the same bytes foreverBUILD ONCE, VERIFY ANYWHERE, DEPLOY BY DIGEST

Stages

9 stages, in order

All lesson pages are readable, including locked stages. Locks apply only to verified project work: complete the previous stage before submitting the next one. Time labels are estimates for reading, implementation, and debugging; your pace will vary.

Phase 1Stages 1–30 of 3 stages verified

Phase 1 — From process to image

Understand the kernel boundaries, build the first image, and shrink it without hiding what disappeared.

  • Name the boundary70 minutes (locked)

    What is a container, without the marketing fog?

    You will be able to create a notes file that explains containers as processes, not VMs.

    Fork the project repository to start working through the stages.

    Read what this stage covers
  • Build the first image90 minutes (locked)

    How does a Dockerfile become a runnable image?

    You will be able to add a root Dockerfile that starts from golang:1.22-bookworm.

    Fork the project repository to start working through the stages.

    Read what this stage covers
  • Shrink it honestly2 hours (locked)

    How do you remove the compiler without removing the program?

    You will be able to rewrite the Dockerfile as a multi-stage build named build and runtime.

    Fork the project repository to start working through the stages.

    Read what this stage covers
Phase 2Stages 4–50 of 2 stages verified

Phase 2 — Runtime trust starts small

Run Beacon with least privilege and make the image describe exactly which source produced it.

  • Drop root early90 minutes (locked)

    What changes when the process inside the container is not root?

    You will be able to ensure the final image runs as a numeric non-root UID and GID.

    Fork the project repository to start working through the stages.

    Read what this stage covers
  • Stamp the image80 minutes (locked)

    How can an image say exactly where it came from?

    You will be able to add build args for VERSION, VCS_REF, CREATED, and SOURCE_DATE_EPOCH.

    Fork the project repository to start working through the stages.

    Read what this stage covers
Phase 3Stages 6–80 of 3 stages verified

Phase 3 — Publish, inspect, prove

Push by digest, inventory and scan the artifact, then sign it with verifiable identity.

  • Publish by digest90 minutes (locked)

    What really happens when an image is pushed to a registry?

    You will be able to document GitLab Container Registry login using docker login registry.gitlab.com --password-stdin.

    Fork the project repository to start working through the stages.

    Read what this stage covers
  • Inventory the image2 hours (locked)

    How do you know what is inside an image you built?

    You will be able to generate an SPDX JSON SBOM for the Beacon runtime image with Syft.

    Fork the project repository to start working through the stages.

    Read what this stage covers
  • Prove who built it2 hours (locked)

    How can someone verify the image came from your workflow?

    You will be able to install or run Cosign without committing any private key.

    Fork the project repository to start working through the stages.

    Read what this stage covers
Phase 4Stage 90 of 1 stages verified

Phase 4 — A local stack

Run the packaged service locally with Compose, health checks, configuration, and durable SQLite storage.

  • Run the local stack2 hours (locked)

    How do containers find each other and keep state on a laptop?

    You will be able to create compose.yaml with no obsolete top-level version: key.

    Fork the project repository to start working through the stages.

    Read what this stage covers

Course overview

A service that only runs on the author's laptop is not a service yet. Container images turn Beacon's binary, runtime files, metadata, and operating assumptions into an artifact another machine can pull, inspect, verify, and run the same way.

What you will learn: Dockerfile multi-stage builds, Non-root container images, SBOM generation with Syft, Container vulnerability scanning, Cosign keyless image signing. Build the project through cumulative challenges with beginner explanations and local verification.

Level
Complete beginner to independently building and operating the project
Format
9 cumulative stages. Every stage teaches the concept in full before any code, then gives you the thing to build and the run that proves it works
Official documentation