27 — Glossary

Read this first: the words that get used as though everyone already knows them. Use this from day one — it is not a reward for finishing. Each entry says what the thing is, not what it is for, and points at the lesson where you meet it.

Shell and Linux

Shell — a program that reads a line of text, finds the program you named, and runs it with your arguments. bash is one. 01

Exit code — the number a program returns when it finishes. Zero is success; anything else is failure. This is how CI decides pass or fail. 01

stdout / stderr — two separate output streams. > redirects only the first; 2> the second; 2>&1 sends errors to wherever output is going. 01

Pipe (|) — connects one program's stdout to the next one's stdin. A pipeline reports only its last command's exit code unless pipefail is set. 01

Shebang — the #!/usr/bin/env bash on line 1 that says which interpreter runs the file. Must be the first line. 02

Word splitting — the shell chopping an unquoted variable at every space before the command sees it. The reason to quote every expansion. 02

errexit / nounset / pipefail — the three halves of set -euo pipefail: stop on failure, refuse unset variables, do not let a pipeline hide a failed stage. errexit is suspended inside if, &&, || and !. 03

Parameter expansion — cutting a string while expanding it: ${var#pattern} from the left, ${var%pattern} from the right, doubled is greedier. 04

Process substitution (< <(...)) — makes a command's output look like a file. Used instead of a pipe so a loop runs in the current shell and its variable assignments survive. 04

Subshell — a child shell. Anything on the right of a pipe runs in one, so variables set there are lost when it exits. 04

umask — the mask of permission bits removed from newly created files. umask 077 gives 600 files and 700 directories. 11

Daemon — a program that runs in the background with no terminal. dockerd is the Docker daemon.

systemd — the init system on most Linux distributions: starts services at boot, restarts them when they die, and collects their logs. Not present in containers.

Containers

Image — a stack of read-only filesystem layers plus a default command. Built once, run many times. 05

Container — one running process using an image's filesystem, with its own view of the network and process list. Not a virtual machine — it shares your kernel. 05

Layer — the filesystem change produced by one Dockerfile instruction. Cached individually; invalidating one invalidates every layer after it. 06

Build context — the directory sent to the Docker daemon, named by the final argument to docker build. COPY can only see what is in it. 06

.dockerignore — what to exclude from the build context. Not optional. 06

Multi-stage build — several FROM lines in one Dockerfile, where a later stage copies artefacts out of an earlier one, leaving the build tools behind. 07

Exec form vs shell form — ENTRYPOINT ["java", "-jar", "x.jar"] makes your process PID 1; ENTRYPOINT java -jar x.jar makes /bin/sh PID 1 and your process never receives SIGTERM. 06

Volume — storage managed by Docker that outlives the container using it. The only thing that survives docker rm. 05

Healthcheck — a command Docker runs periodically to decide whether a container is healthy. What a deploy gate waits on. 08

start_period — a healthcheck's grace window; failures during it do not count against retries. 08

Compose project — a named group of services with its own lifecycle. Four of them share the production host. 25

Registry — where images live between being built and being run. GHCR is GitHub's. 16

Tag vs digest — a tag is a movable label (latest); a digest is the immutable sha256: hash of exact content. 16

CI/CD

Runner — the temporary machine GitHub rents you to run a workflow. Destroyed afterwards. 15

Workflow — one YAML file in .github/workflows/. Job — steps sharing one runner; parallel by default. Step — one run: or uses:. 15

Action — a reusable step published by someone else, referenced with uses: owner/name@v4. Always pin the version. 16

Artifact — a file uploaded from one job so another job (or a human) can download it. How files cross job boundaries. 17

GITHUB_TOKEN — a credential minted for each run and expiring with it. What it may do is set by permissions:, and declaring that block zeroes every unlisted scope. 16

Environment — a named GitHub setting that is also a secrets scope. A job that does not declare it reads its secrets as empty strings. 17

Concurrency group — keeps one run executing and at most one pending; a third arrival replaces the pending one rather than queueing. 17

Reusable workflow — a workflow declaring on: workflow_call, callable as a job by another. 17

Workflow command — a specially formatted log line such as ::error:: that GitHub surfaces in the run summary. 15

Health gate — the step where a deploy waits for the new version to report healthy, and rolls back if it does not. 18

Promote — deploy an existing tested image to production rather than rebuilding it. 20

Build once, deploy twice — the rule that production runs the same bytes staging proved, not a rebuild from the same commit. 20

Networking

Reverse proxy — a server that receives every request and forwards it to whichever backend should handle it. Caddy is one; nginx is another. 25

Edge — the outermost component, the only one publishing ports. 25

Publishing a port (-p 8080:80) — mapping a host port to a container port. Host first. A service with no ports: is unreachable from outside its network. 05

0.0.0.0 vs 127.0.0.1 — listening on every interface versus loopback only. The whole exposure story in one column of ss -tlnp. 12

X-Forwarded-For — a header carrying the original client IP through proxies. Trustworthy only when the number of hops is guaranteed. 25

DOCKER-USER — the iptables chain evaluated before Docker's own accept rules, and the only place a firewall rule can win. It sees forwarded traffic in both directions. 13

ACME / Let's Encrypt — the protocol and the authority that issue TLS certificates automatically. Requires that the issuer can reach your server. 25

SSH keypair — a public key you distribute and a private key you never do. The server stores the public half in authorized_keys. 10

SSH tunnel (-L) — forwards a local port to a port on the remote host, which is how you reach a service bound to the server's loopback. 12

Across machines

Bridge network — Docker's default network driver. Local to one daemon, which is why container names stop resolving the moment a service moves to another host. 29

Overlay network — a network that spans hosts, provided by an orchestrator (Swarm, Kubernetes). This repository has none; every network in it is a bridge. 29

Service discovery — backends registering themselves so the proxy learns about them, instead of being listed in a file. Traefik's Docker provider is one. 30

Private networking — a provider-supplied network between your own servers that never touches the public internet. The simplest way to connect a split stack. 29

Router / service / middleware — Traefik's three pieces: a rule that matches requests, the backends they go to, and anything applied in between. 30

Entrypoint — a port a proxy listens on. Traefik names them (web, websecure). 30

pg_hba.conf — PostgreSQL's own access list: who may connect, from where, and whether TLS is required. Independent of, and in addition to, the firewall. 29

sslmode=verify-full — a Postgres client setting that encrypts and verifies the server's identity. require only encrypts, which does not stop an impostor. 29

Session vs transaction pooling — how a connection pooler such as PgBouncer hands out connections. This application sets a per-connection session variable for tenant isolation, so transaction pooling would break it; only session pooling is safe here.

Horizontal vs vertical scaling — more machines versus a bigger machine. Vertical needs no code change; horizontal needs the shared-state work in scaling.md.

Data

Migration — a versioned, forward-only change to a database schema. Flyway runs them at startup. Rollback restores code, not data — which is why migrations must always go forwards. 19

Dump — a portable text export of a database (pg_dump), as opposed to a copy of its raw storage.

The two most useful sentences here

Zero is success; anything else is failure. Everything in CI is that one fact wearing costumes.

A container is a process, not a machine. Almost every wrong prediction about Docker comes from forgetting it.