Project challenges / verified progress
Beacon: package it so anyone can run it

The engineering notebook

Stamp the image

How can an image say exactly where it came from?

Loading Vault account...
Phase 2 — Runtime trust starts small

Step 01 of 06

Understand the idea

An image can run correctly and still be hard to identify later. Add metadata such as its version, build time, and source location so a teammate can inspect the image and find out how it was made.

COMMIT TO IMAGE ID01Git commitrevision and sourceimmutable02Build argscreated version refCI fills03OCI labelsmetadata in configinspectable04Digesthash of contenttruth
Labels answer who built this and from what. The digest answers what bytes this name refers to. You want both, because provenance without content identity is a nice story attached to a movable thing.
Step 01

Key technical ideas

Labels are metadata, not filesystem files

A Docker LABEL instruction writes key-value data into the image configuration. It does not create /labels.txt and it does not change how Beacon runs. The OCI keys are conventional names other tools understand: source repository, revision, creation time, licences, title, and description. They make inspection cheap and automation boring.

Build args are inputs, not secrets

ARG VCS_REF lets docker build --build-arg VCS_REF=$(git rev-parse HEAD) stamp the commit. Build args can appear in image history and metadata, so never pass tokens through them. They are excellent for public facts: version, source URL, created timestamp, and revision.

Reproducibility removes accidental time travel

Two builds from the same commit should be as similar as the toolchain allows. SOURCE_DATE_EPOCH gives tools a stable timestamp instead of wall-clock time. Go also needs flags such as -trimpath and controlled version variables. Perfect reproducibility is hard; knowing which inputs break it is already a professional step up.

Latest is a nickname with no memory

beacon:latest can point to one image at noon and another at 12:05. Nothing in the tag name records the change. A digest such as sha256:... is computed from content and changes when the content changes. Deployments that need repeatability pin digests and use labels to explain them.

Inspecting an OCI label
docker image inspect beacon:meta   --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'

The label is retrieved from image configuration, not from inside the container. You do not need to start Beacon to ask where the image came from.

Names and identities

ReferenceCan change?Use it for

latest

Yes

Local convenience only

v1.2.3

Technically yes

Human release name

Immutable tag

Policy says no

Registry workflow

Digest

No

Deployment identity

Technical terms used at work

  • OCI annotation — A standard image metadata key such as org.opencontainers.image.source.

  • Digest — A content hash identifying image bytes, commonly sha256:....

  • Build arg — A Dockerfile input supplied at build time with --build-arg.