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.
Your learning trail
Verified project-agent submissions only. Reading or clicking cannot unlock progress.
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 GHCR, inventories and scans it, signs the pushed digest, and finally runs the service locally with Compose, a health check, and a named SQLite volume.
Stages
9 stages, in order
Expand any stage to read what it teaches. A stage opens for work once the stage before it passes a verified submission.
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.
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.
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.
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.
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.
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 GHCR login using docker login ghcr.io --password-stdin.
Fork the project repository to start working through the stages.
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.
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.
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.
About this path
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
- Before you start
- Docker Engine 25+ with Docker Compose v2, or a compatible Podman/Colima setup; Go 1.22+; and a free GitHub account for GitHub Container Registry. Public images on `ghcr.io` cost nothing, and no cloud provider account is required.