Skip to content

qtsone/learning / skills/tutor

tutor

Flagged

Turn this agent into a personal programming tutor with a versioned 0-to-expert curriculum (Go available; more languages coming). Use when the user wants to learn a programming language, start or resume lessons, get their exercise code graded, check learning progress, or contribute curriculum fixes — e.g. "/tutor go", "/tutor resume", "teach me Go", "continue my lessons", "grade my exercise".

FileKindSize
SKILL.mdskill md9.2 KB
curriculum/content/focus/cli-tooling/capstone/LESSON.mdmarkdown17.1 KB
curriculum/content/focus/cli-tooling/capstone/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/app.goscript5.8 KB
curriculum/content/focus/cli-tooling/capstone/exercise/authors.goscript1.6 KB
curriculum/content/focus/cli-tooling/capstone/exercise/authors_test.goscript7.3 KB
curriculum/content/focus/cli-tooling/capstone/exercise/cli_test.goscript11.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/config_test.goscript11.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/go.modmanifest187 B
curriculum/content/focus/cli-tooling/capstone/exercise/go.summanifest900 B
curriculum/content/focus/cli-tooling/capstone/exercise/main.goscript2.0 KB
curriculum/content/focus/cli-tooling/capstone/exercise/render.goscript1.9 KB
curriculum/content/focus/cli-tooling/capstone/exercise/root.goscript2.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/scan.goscript2.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/scan_test.goscript4.0 KB
curriculum/content/focus/cli-tooling/capstone/exercise/signal_unix_test.goscript1.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/version.goscript942 B
curriculum/content/focus/cli-tooling/capstone/quiz.jsonconfig5.0 KB
curriculum/content/focus/cli-tooling/capstone/solution/app.goscript9.9 KB
curriculum/content/focus/cli-tooling/capstone/solution/authors.goscript2.9 KB
curriculum/content/focus/cli-tooling/capstone/solution/render.goscript2.6 KB
curriculum/content/focus/cli-tooling/capstone/solution/root.goscript4.7 KB
curriculum/content/focus/cli-tooling/capstone/solution/scan.goscript3.7 KB
curriculum/content/focus/cli-tooling/cobra/LESSON.mdmarkdown12.8 KB
curriculum/content/focus/cli-tooling/cobra/TUTOR.mdmarkdown5.9 KB
curriculum/content/focus/cli-tooling/cobra/exercise/app.goscript1.7 KB
curriculum/content/focus/cli-tooling/cobra/exercise/go.modmanifest193 B
curriculum/content/focus/cli-tooling/cobra/exercise/go.summanifest900 B
curriculum/content/focus/cli-tooling/cobra/exercise/main.goscript422 B
curriculum/content/focus/cli-tooling/cobra/exercise/notes_test.goscript9.8 KB
curriculum/content/focus/cli-tooling/cobra/exercise/root.goscript919 B
curriculum/content/focus/cli-tooling/cobra/exercise/store.goscript1.7 KB
curriculum/content/focus/cli-tooling/cobra/quiz.jsonconfig5.1 KB
curriculum/content/focus/cli-tooling/cobra/solution/app.goscript2.4 KB
curriculum/content/focus/cli-tooling/cobra/solution/root.goscript4.2 KB
curriculum/content/focus/cli-tooling/distribution/LESSON.mdmarkdown17.2 KB
curriculum/content/focus/cli-tooling/distribution/TUTOR.mdmarkdown7.0 KB
curriculum/content/focus/cli-tooling/distribution/exercise/check.shexecutablescript12.0 KB
curriculum/content/focus/cli-tooling/distribution/exercise/go.modmanifest35 B
curriculum/content/focus/cli-tooling/distribution/exercise/internal/buildinfo/buildinfo.goscript1.4 KB
curriculum/content/focus/cli-tooling/distribution/exercise/main.goscript1.2 KB
curriculum/content/focus/cli-tooling/distribution/quiz.jsonconfig5.0 KB
curriculum/content/focus/cli-tooling/distribution/solution/.goreleaser.yamlconfig2.1 KB
curriculum/content/focus/cli-tooling/distribution/solution/internal/buildinfo/buildinfo.goscript1.3 KB
curriculum/content/focus/cli-tooling/files-processes/LESSON.mdmarkdown18.8 KB
curriculum/content/focus/cli-tooling/files-processes/TUTOR.mdmarkdown7.8 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/atomicfile.goscript772 B
curriculum/content/focus/cli-tooling/files-processes/exercise/atomicfile_test.goscript2.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/exec.goscript3.8 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/exec_test.goscript10.7 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/go.modmanifest44 B
curriculum/content/focus/cli-tooling/files-processes/exercise/main.goscript1.9 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/paths.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/paths_test.goscript3.1 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal_test.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal_unix_test.goscript2.4 KB
curriculum/content/focus/cli-tooling/files-processes/quiz.jsonconfig7.9 KB
curriculum/content/focus/cli-tooling/files-processes/solution/atomicfile.goscript2.1 KB
curriculum/content/focus/cli-tooling/files-processes/solution/exec.goscript5.4 KB
curriculum/content/focus/cli-tooling/files-processes/solution/paths.goscript2.2 KB
curriculum/content/focus/cli-tooling/files-processes/solution/signal.goscript2.1 KB
curriculum/content/focus/cli-tooling/flags-config/LESSON.mdmarkdown12.3 KB
curriculum/content/focus/cli-tooling/flags-config/TUTOR.mdmarkdown6.7 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/config.goscript2.4 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/config_test.goscript3.1 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/flagvalue.goscript769 B
curriculum/content/focus/cli-tooling/flags-config/exercise/flagvalue_test.goscript1.9 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/go.modmanifest41 B
curriculum/content/focus/cli-tooling/flags-config/exercise/loader.goscript5.5 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/loader_test.goscript12.4 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/main.goscript1.2 KB
curriculum/content/focus/cli-tooling/flags-config/quiz.jsonconfig5.3 KB
curriculum/content/focus/cli-tooling/flags-config/solution/config.goscript3.2 KB
curriculum/content/focus/cli-tooling/flags-config/solution/flagvalue.goscript957 B
curriculum/content/focus/cli-tooling/flags-config/solution/loader.goscript9.0 KB
curriculum/content/focus/cli-tooling/terminal-ux/LESSON.mdmarkdown14.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/TUTOR.mdmarkdown6.2 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/color.goscript1.6 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/color_test.goscript2.3 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/go.modmanifest40 B
curriculum/content/focus/cli-tooling/terminal-ux/exercise/main.goscript3.6 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/progress.goscript1.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/progress_test.goscript1.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/prompt.goscript2.3 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/prompt_test.goscript4.7 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/render.goscript3.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/render_test.goscript6.1 KB
curriculum/content/focus/cli-tooling/terminal-ux/quiz.jsonconfig5.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/color.goscript1.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/progress.goscript2.0 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/prompt.goscript2.2 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/render.goscript4.3 KB
curriculum/content/focus/containers/capstone/LESSON.mdmarkdown20.0 KB
curriculum/content/focus/containers/capstone/TUTOR.mdmarkdown6.7 KB
curriculum/content/focus/containers/capstone/exercise/.dockerignoreother190 B
curriculum/content/focus/containers/capstone/exercise/.github/workflows/release.ymlconfig2.4 KB
curriculum/content/focus/containers/capstone/exercise/Dockerfileother903 B
curriculum/content/focus/containers/capstone/exercise/RUNBOOK.mdmarkdown1.6 KB
curriculum/content/focus/containers/capstone/exercise/check.shscript62.6 KB
curriculum/content/focus/containers/capstone/exercise/deploy/base/deployment.yamlconfig2.8 KB
curriculum/content/focus/containers/capstone/exercise/deploy/base/kustomization.yamlconfig845 B
curriculum/content/focus/containers/capstone/exercise/deploy/base/service.yamlconfig316 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/dev/kustomization.yamlconfig1.3 KB
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/dev/resources-patch.yamlconfig906 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/prod/kustomization.yamlconfig899 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/prod/resources-patch.yamlconfig341 B
curriculum/content/focus/containers/capstone/exercise/go.modmanifest48 B
curriculum/content/focus/containers/capstone/exercise/main.goscript6.4 KB
curriculum/content/focus/containers/capstone/quiz.jsonconfig6.5 KB
curriculum/content/focus/containers/capstone/solution/.github/workflows/release.ymlconfig6.4 KB
curriculum/content/focus/containers/capstone/solution/Dockerfileother1.2 KB
curriculum/content/focus/containers/capstone/solution/RUNBOOK.mdmarkdown7.7 KB
curriculum/content/focus/containers/capstone/solution/deploy/overlays/prod/kustomization.yamlconfig1.4 KB
curriculum/content/focus/containers/capstone/solution/deploy/overlays/prod/resources-patch.yamlconfig1.1 KB
curriculum/content/focus/containers/compose/LESSON.mdmarkdown13.5 KB
curriculum/content/focus/containers/compose/TUTOR.mdmarkdown5.2 KB
curriculum/content/focus/containers/compose/exercise/.env.exampleother348 B
curriculum/content/focus/containers/compose/exercise/app/Dockerfileother962 B
curriculum/content/focus/containers/compose/exercise/app/go.modmanifest40 B
curriculum/content/focus/containers/compose/exercise/app/main.goscript2.2 KB
curriculum/content/focus/containers/compose/exercise/check.shscript24.5 KB
curriculum/content/focus/containers/compose/exercise/compose.yamlconfig877 B
curriculum/content/focus/containers/compose/quiz.jsonconfig4.5 KB
curriculum/content/focus/containers/compose/solution/.envconfig203 B
curriculum/content/focus/containers/compose/solution/compose.yamlconfig1.6 KB
curriculum/content/focus/containers/deploying-go/LESSON.mdmarkdown21.1 KB
curriculum/content/focus/containers/deploying-go/TUTOR.mdmarkdown6.5 KB
curriculum/content/focus/containers/deploying-go/exercise/.dockerignoreother150 B
curriculum/content/focus/containers/deploying-go/exercise/Dockerfileother851 B
curriculum/content/focus/containers/deploying-go/exercise/SHUTDOWN.mdmarkdown1.4 KB
curriculum/content/focus/containers/deploying-go/exercise/check.shscript43.5 KB
curriculum/content/focus/containers/deploying-go/exercise/configmap.yamlconfig526 B
curriculum/content/focus/containers/deploying-go/exercise/deployment.yamlconfig2.5 KB
curriculum/content/focus/containers/deploying-go/exercise/go.modmanifest41 B
curriculum/content/focus/containers/deploying-go/exercise/main.goscript6.1 KB
curriculum/content/focus/containers/deploying-go/exercise/service.yamlconfig347 B
curriculum/content/focus/containers/deploying-go/exercise/shutdown_test.goscript3.3 KB
curriculum/content/focus/containers/deploying-go/quiz.jsonconfig6.5 KB
curriculum/content/focus/containers/deploying-go/solution/SHUTDOWN.mdmarkdown5.4 KB
curriculum/content/focus/containers/deploying-go/solution/configmap.yamlconfig541 B
curriculum/content/focus/containers/deploying-go/solution/deployment.yamlconfig4.0 KB
curriculum/content/focus/containers/deploying-go/solution/main.goscript6.1 KB
curriculum/content/focus/containers/docker-fundamentals/LESSON.mdmarkdown14.4 KB
curriculum/content/focus/containers/docker-fundamentals/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/Dockerfileother261 B
curriculum/content/focus/containers/docker-fundamentals/exercise/NOTES.mdmarkdown1.4 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/check.shscript10.7 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/go.modmanifest38 B
curriculum/content/focus/containers/docker-fundamentals/exercise/local.envconfig218 B
curriculum/content/focus/containers/docker-fundamentals/exercise/main.goscript780 B
curriculum/content/focus/containers/docker-fundamentals/exercise/scratch/notes.mdmarkdown153 B
curriculum/content/focus/containers/docker-fundamentals/quiz.jsonconfig5.5 KB
curriculum/content/focus/containers/docker-fundamentals/solution/.dockerignoreother230 B
curriculum/content/focus/containers/docker-fundamentals/solution/Dockerfileother504 B
curriculum/content/focus/containers/docker-fundamentals/solution/NOTES.mdmarkdown3.8 KB
curriculum/content/focus/containers/dockerizing-go/LESSON.mdmarkdown14.0 KB
curriculum/content/focus/containers/dockerizing-go/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/containers/dockerizing-go/exercise/.dockerignoreother143 B
curriculum/content/focus/containers/dockerizing-go/exercise/Dockerfile.naiveother512 B
curriculum/content/focus/containers/dockerizing-go/exercise/NOTES.mdmarkdown1.1 KB
curriculum/content/focus/containers/dockerizing-go/exercise/check.shscript14.2 KB
curriculum/content/focus/containers/dockerizing-go/exercise/go.modmanifest43 B
curriculum/content/focus/containers/dockerizing-go/exercise/go.summanifest0 B
curriculum/content/focus/containers/dockerizing-go/exercise/main.goscript1.7 KB
curriculum/content/focus/containers/dockerizing-go/quiz.jsonconfig4.5 KB
curriculum/content/focus/containers/dockerizing-go/solution/Dockerfileother755 B
curriculum/content/focus/containers/dockerizing-go/solution/NOTES.mdmarkdown2.7 KB
curriculum/content/focus/containers/helm-kustomize/LESSON.mdmarkdown19.1 KB
curriculum/content/focus/containers/helm-kustomize/TUTOR.mdmarkdown9.5 KB
curriculum/content/focus/containers/helm-kustomize/exercise/NOTES.mdmarkdown1.5 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/Chart.yamlconfig518 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/_helpers.tplother1.8 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/configmap.yamlconfig392 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/deployment.yamlconfig3.2 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/service.yamlconfig512 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/values.yamlconfig1.4 KB
curriculum/content/focus/containers/helm-kustomize/exercise/check.shscript55.4 KB
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/deployment.yamlconfig2.1 KB
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/kustomization.yamlconfig798 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/service.yamlconfig347 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/dev/kustomization.yamlconfig616 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/dev/resources-patch.yamlconfig506 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/prod/kustomization.yamlconfig477 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/prod/resources-patch.yamlconfig614 B
curriculum/content/focus/containers/helm-kustomize/quiz.jsonconfig7.4 KB
curriculum/content/focus/containers/helm-kustomize/solution/NOTES.mdmarkdown3.3 KB
curriculum/content/focus/containers/helm-kustomize/solution/chart/Chart.yamlconfig366 B
curriculum/content/focus/containers/helm-kustomize/solution/chart/templates/configmap.yamlconfig547 B
curriculum/content/focus/containers/helm-kustomize/solution/chart/templates/deployment.yamlconfig2.5 KB
curriculum/content/focus/containers/helm-kustomize/solution/chart/values.yamlconfig1.2 KB
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/base/kustomization.yamlconfig915 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/dev/kustomization.yamlconfig820 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/dev/resources-patch.yamlconfig515 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/prod/kustomization.yamlconfig267 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/prod/resources-patch.yamlconfig649 B
curriculum/content/focus/containers/kubernetes-config/LESSON.mdmarkdown19.4 KB
curriculum/content/focus/containers/kubernetes-config/TUTOR.mdmarkdown6.3 KB
curriculum/content/focus/containers/kubernetes-config/exercise/NOTES.mdmarkdown1.3 KB
curriculum/content/focus/containers/kubernetes-config/exercise/app/Dockerfileother1.0 KB

curriculum/content/focus/containers/docker-fundamentals/LESSON.md

View on GitHub
# Docker Fundamentals

> `focus.containers.docker-fundamentals` · ~2-3h · Stage: Focus: Containers I

## Objectives

By the end of this lesson you can:

- Explain the difference between an image and a container, and how a
  container's writable layer relates to the image's read-only layers.
- Explain how image layers are built and cached, and predict which Dockerfile
  changes invalidate the cache.
- Run, inspect, stop, and remove containers with `docker` CLI commands,
  including port publishing and log inspection.
- Pull and push images to a registry, and explain how tags and digests
  identify images.
- Explain how namespaces and cgroups make a container different from a virtual
  machine.

You will get much more out of this lesson with
[Docker installed](https://docs.docker.com/get-started/get-docker/), so install
it if you can. It is not required to pass: the exercise grades the files you
write, daemon or no daemon.

## A container is a process, not a small computer

You will hear "a container is a lightweight VM" constantly. It is wrong, and
believing it will mislead you about performance, security, and half the errors
you hit. Kill it now.

Run `ps` on your machine: dozens of processes, all sharing one kernel. A
container is one of those processes — started with a *restricted view of the
system* and a *ceiling on what it may consume*. Two Linux kernel features do
that work:

**Namespaces — what a process can see.** A namespace is a lie the kernel tells
a process about the world, and a container typically gets one of each kind:

- *PID*: its own process tree. Its main process is PID 1 and cannot see host
  processes at all.
- *Mount*: its own filesystem root. What it calls `/` is a tree assembled from
  the image, not your `/`.
- *Network*: its own interfaces, routes, and port space. Two containers can
  both "listen on 8080" without colliding — those are two different 8080s.
- *UTS, IPC, user*: its own hostname, shared-memory objects, and user-ID
  mapping.

**Cgroups (control groups) — what a process can use.** A cgroup caps CPU time,
memory, and I/O for a group of processes. `docker run --memory=64m` is a cgroup
limit; exceed it and the kernel OOM-kills your process. There is no virtual RAM
chip anywhere.

Contrast a virtual machine: a hypervisor emulates hardware, a *second kernel*
boots on it, and a full operating system runs inside — seconds of boot time and
hundreds of megabytes of RAM before your code runs. A container adds neither.

Four consequences worth carrying:

1. **A Linux container needs a Linux kernel.** On macOS and Windows, Docker
   quietly runs a small Linux VM and puts your containers inside it. That
   hidden VM is exactly why people conflate the two ideas.
2. **The "operating system" inside an image is only userland.** A Debian image
   ships Debian's files and libraries — `/bin`, `/lib`, package manager — but
   uses *your* kernel. No init, no kernel, no boot.
3. **Isolation is thinner than a VM's.** One shared kernel is one shared attack
   surface; for hostile multi-tenant workloads people still reach for VMs.
4. **You cannot cheat the kernel.** No Windows containers on a Linux kernel;
   no kernel modules from inside a container.

## Images and containers

An **image** is a read-only template: a stack of filesystem layers plus metadata
(default command, environment variables, working directory, user, declared
ports). It is inert. A **container** is an image, plus a thin **writable layer**
on top, plus a process running inside the namespaces and cgroup above.

You know this relationship from S1: an image is the compiled binary on disk, a
container is a process you started from it. One binary, many processes, each
with its own memory. One image, many containers, each with its own writable
layer.

That writable layer is the part people get wrong. Every file your program
creates or modifies while running lands there, not in the image — a running
container never modifies its image. And `docker rm` deletes the writable layer
along with the container. Data you want to keep has to live somewhere else;
that "somewhere else" is a volume, and it is the third lesson of this pack.

## Layers and the union filesystem

Each Dockerfile instruction that changes the filesystem produces a **layer**: a
diff — files added, changed, deleted — named by the SHA-256 digest of its
content. At run time the layers are stacked into a single directory tree by a **union
filesystem** (usually OverlayFS). Reading a path finds it in the topmost layer
that has it. Writing copies the file up into the writable layer first and edits
the copy — **copy-on-write**. Deleting a file that lives in a lower layer does
not remove those bytes; it writes a *whiteout* marker above that hides them.

That last sentence has a security consequence people learn the hard way:

```dockerfile
COPY secrets.env .
RUN rm secrets.env      # the file is hidden, not gone
```

The bytes are still sitting in the earlier layer, and anyone who pulls the
image can read them. Secrets must never enter the build in the first place —
which is what `.dockerignore` is for, and why you will write one today.

Layers are content-addressed, so they are shared: if two images build on the
same base, that base is stored once on disk and downloaded once. "This image is
900 MB" often means "899 MB of it you already had".

## The build cache

For each instruction, the builder computes a cache key from the parent layer's
digest plus the instruction itself — and for `COPY`/`ADD`, plus a checksum of
the files being copied. If a layer with that key already exists, it is reused
and the instruction never runs. **The first miss invalidates every instruction
after it**, because each key includes the parent.

So instruction order is a performance decision: put what changes rarely at the
top, what changes constantly at the bottom. For a Go program the canonical
shape is:

```dockerfile
COPY go.mod go.sum ./
RUN go mod download      # cached until your dependencies change
COPY . .                 # misses on every source edit
RUN go build -o /bin/app .
```

Invert those and you re-download every dependency for a one-character typo fix,
because `COPY . .` misses and drags `go mod download` down with it. (The
exercise module has no third-party dependencies yet, so it has no `go.sum` —
copy `go.mod` alone. The shape is what matters.)

Two more cache habits: chain package-manager commands into one `RUN`
(`apt-get update && apt-get install -y …`, or a cached `update` layer feeds a
months-stale package index into `install`), and keep junk out of the build
context, since a stray edit to a notes file busts `COPY . .` all by itself.

## Tags, digests, and why `latest` is not a version

A full image reference looks like:

```
ghcr.io/ada/clockwork:1.4.0
└─ registry ┘└ repository ┘└ tag ┘
```

A **tag** is a mutable, human-friendly pointer to an image; the publisher moves
it whenever they like — that is the *point* of `golang:1.22`, which slides
forward as patch releases land.

`latest` is not special. It is simply the tag Docker assumes when you do not
name one. Nothing guarantees it points at the newest release, and it moves
without warning. `FROM node:latest` is how a pipeline green on Monday goes red
on Wednesday with no commit in between — and the Monday image cannot be
reproduced, so you cannot bisect.

A **digest** is the SHA-256 of the image content, so it is an identity rather
than a pointer: `FROM golang:1.22-bookworm@sha256:8a9f…` resolves to exactly
the same bytes forever. The price is that you now own updating it — usually
delegated to a bot that opens a pull request when the tag moves.

The working rule: never `latest`; always a concrete tag; add a digest when you
need real reproducibility (releases, base images, anything you deploy).

## Registries

A **registry** stores repositories of tagged images: Docker Hub (the default),
GitHub Container Registry (`ghcr.io`), and every cloud provider's own.

```sh
docker pull golang:1.22-bookworm          # Docker Hub implied
docker login ghcr.io                      # credentials before pushing
docker tag clockwork:1.4.0 ghcr.io/ada/clockwork:1.4.0
docker push ghcr.io/ada/clockwork:1.4.0
```

Omit the registry and Docker Hub is assumed; omit the namespace too (`golang`,
`postgres`) and you get Hub's curated `library/` images. Pulls also happen
implicitly — `docker run` on an image you lack pulls it first. Pushing is
almost always CI's job rather than your laptop's; you built that muscle in S4
and this pack's capstone will use it. One operational surprise: Docker Hub
rate-limits anonymous pulls, so a pipeline suddenly reporting "too many
requests" is usually hitting that, not a bug.

## The command vocabulary

```sh
docker build -t clockwork:1.0.0 .   # build an image; "." is the build context
docker run -d -p 8080:8080 --name clock clockwork:1.0.0
docker ps                           # running containers
docker ps -a                        # including stopped ones
docker logs -f clock                # stream stdout/stderr
docker exec -it clock sh            # a second process inside the container
docker stop clock                   # SIGTERM, then SIGKILL after ~10s
docker rm clock                     # delete the container and its writable layer
docker image ls                     # local images
docker image rm clockwork:1.0.0
docker system df                    # what all this is costing you on disk
```

Five of those deserve a note:

- **The `.` in `build` is the build context**, not "here". That directory tree
  is packed up and handed to the daemon before the build starts, and `COPY` can
  only read from it. Big context, slow builds — hence `.dockerignore`.
- **`-p 8080:8080` is `host:container`.** The container has its own network
  namespace, so its port is unreachable from your machine until you publish it.
  `EXPOSE` in a Dockerfile does *not* do this; it is documentation.
- **`docker logs` reads the container's stdout and stderr** — which is why
  containerized programs log to standard output instead of to files. The
  platform collects streams, not files.
- **`docker exec` starts an extra process inside an existing container's
  namespaces** — not a new container. It is your main debugging tool, and it
  fails on minimal images with no shell, a tradeoff the next lesson makes
  deliberately.
- **`docker stop` sends SIGTERM first**, giving your program a window to shut
  down cleanly, then SIGKILL. Your process is PID 1, so it receives that signal
  directly — *if* it is really PID 1. Which brings us to:

## CMD, ENTRYPOINT, exec form and shell form

`CMD` and `ENTRYPOINT` both declare what runs when the container starts —
roughly, `ENTRYPOINT` is the command and `CMD` its default arguments; with only
`CMD`, it is the whole command. Each accepts two syntaxes, and the difference is
not cosmetic:

```dockerfile
CMD ["/bin/clockwork"]     # exec form  — your binary is PID 1
CMD /bin/clockwork         # shell form — /bin/sh -c "/bin/clockwork" is PID 1
```

In shell form the container's PID 1 is a shell, and a plain `sh` does not
forward signals to its child. `docker stop` then hits the shell, your program
never sees SIGTERM, and ten seconds later everything is SIGKILLed mid-flight.
Always use exec form for the process you actually want to run.

The other instructions you need today: `FROM` (base image), `WORKDIR`
(absolute working directory for everything after it — set one, don't inherit
whatever the base left you in), `COPY` (context → image), `RUN` (execute at
*build* time, producing a layer), `ENV` (default environment variable),
`EXPOSE` (documentation of the port your program listens on).

One last framing: the `docker` CLI talks to a daemon that does the work, but
the image format and runtime underneath are standardized by the **OCI** (Open
Container Initiative). That is why Podman runs Docker images and why Kubernetes
runs containers with no Docker installed anywhere. Learn the concepts, not the
vendor.

## Exercise

Open [`exercise/`](exercise/). It contains `clockwork`, a tiny HTTP service that
answers every request with the current time and logs each one to stdout. Read
`main.go` but change nothing in it — the few lines that register a handler and
start a server are yours to use, not to design (that is S5's subject). Also in
the folder: a `Dockerfile` a previous owner wrote in ten minutes, and some junk
that should never reach an image.

Rewrite the `Dockerfile`, write a `.dockerignore`, and answer the four
questions in `NOTES.md`. Acceptance criteria:

1. The `Dockerfile` starts `FROM` a base image pinned to a concrete tag or
   digest — never `latest`, never an untagged name. Use Go 1.22 or newer;
   `go.mod` says `go 1.22`.
2. It sets an absolute `WORKDIR` before copying anything.
3. It copies `go.mod` and runs `go mod download` *before* copying the source,
   so an ordinary edit does not invalidate the dependency layer.
4. It copies the source, builds the binary, and declares the start command with
   `CMD` (or `ENTRYPOINT`) in **exec form**.
5. `.dockerignore` excludes at least `.git`, `local.env`, and `scratch/`.
6. `NOTES.md` answers all four questions in your own words, in prose.

Then run the referee, as often as you like:

```sh
cd exercise
bash check.sh
```

It grades your files statically — no daemon, no network, no root — so it works
everywhere. With Docker running it also builds your image as a bonus check;
without Docker those lines say `SKIP` and cost you nothing, and the summary
line tells you how many passed and how many were skipped.

If you have Docker, do the full loop by hand too — it is the point of the
lesson:

```sh
docker build -t clockwork:1.0.0 .
docker run -d -p 8080:8080 --name clock clockwork:1.0.0
curl localhost:8080          # or open it in a browser
docker logs clock            # your request, logged
docker exec -it clock sh     # look around: ls /, ps, hostname
docker stop clock && docker rm clock
docker image ls              # note the size — remember it for the next lesson
```

Then change one line in `main.go`, rebuild, and watch which steps say `CACHED`.

## Further reading

- [Docker docs — What is an image?](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/)
- [Docker docs — Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
- [Docker docs — Build cache](https://docs.docker.com/build/cache/)
- [`namespaces(7)` — Linux manual](https://man7.org/linux/man-pages/man7/namespaces.7.html)
  — the kernel feature itself, with no Docker in sight.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall