# Glossary — Containers & Local Dev

The canonical vocabulary for this course. Opinionated and repo-flavoured. Once a term is
defined here, every lesson uses it this way. Terms marked *(Part 2)* are previewed now and
taught later.

---

### Container
A **running instance of an image** — an isolated process (or process tree) on a host, with its
own filesystem, network, and process view, sharing the host's kernel. Not a VM: no guest OS.
Implemented with Linux **namespaces** (isolation) + **cgroups** (resource limits).
*Repo: every `new-backend:locally` process is a container.*

### Image
A **read-only template** for a container: a stack of filesystem **layers** plus metadata
(entrypoint, env, exposed ports). You *build* an image, then *run* it to get a container.
Conforms to the **OCI Image Spec**. *Repo: built from `local/Dockerfile.development`.*

### Layer
One immutable filesystem diff inside an image, produced by one build instruction. Layers stack
and are **cached** and **shared** across images. Change a layer → every layer after it is
rebuilt. *This is why Dockerfile instruction order matters.*

### Dockerfile
The text recipe that builds an image — one instruction per line, each (roughly) a layer.
`FROM`, `RUN`, `COPY`, `ENV`, `ENTRYPOINT`, `CMD`. *Repo: `local/Dockerfile.development`.*

### Multi-stage build
A Dockerfile with multiple `FROM` stages, where later stages `COPY --from=` earlier ones. Lets
you build with a fat toolchain but ship a lean runtime image. *Repo: the `curl-ready` →
`download-*` → `developer` chain.*

### Base image
The image a stage starts `FROM`. *Repo: `debian:12.11` (chosen over distroless because dev/CI
need shell tools).*

### Registry
A server that stores and serves images (`docker pull` / `push`). *Repo: `asia.gcr.io/...` — a
Google Artifact/Container Registry.*

### Tag
A human label on an image, `name:tag` (e.g. `postgres:15-bookworm`, `new-backend:locally`).
`latest` is just the default tag, not "newest".

### ENTRYPOINT vs CMD
`ENTRYPOINT` = the executable that always runs; `CMD` (or Compose `command:`) = its default
arguments, easily overridden. *Repo: `ENTRYPOINT ["/server"]`, and each Compose service sets
`command:` to pick its service/job.*

### Port mapping (`-p host:container`)
Publishes a container's port on the host. *Repo: `db`'s `"5432:5432"`.* Inside a Docker network
containers reach each other directly by name — mapping is only for host access.

### Volume (named) vs bind mount
**Named volume** — Docker-managed storage that outlives the container (`postgres_data`). **Bind
mount** — a host path mounted into the container (repo configs/secrets). Rule of thumb: named
volumes for *data*, bind mounts for *code/config you edit on the host*.

### Environment variable (`environment:` / `-e`)
Runtime config injected into the container's process. *Repo: `POSTGRES_PASSWORD`,
`GOOGLE_APPLICATION_CREDENTIALS`.*

### Network (bridge)
A virtual network connecting containers so they can talk by **service name** as DNS. *Repo:
`local-manabie-network`; services resolve the DB as `db`.*

### Docker Compose
A tool that defines and runs a **multi-container** app from one YAML file (`services`,
`volumes`, `networks`). *Repo: `local/docker-compose.*.yaml`, driven by `run.bash`.*

### `depends_on` / `service_healthy`
Compose startup ordering. Plain `depends_on` waits only for *start*; `condition:
service_healthy` waits for the dependency's **healthcheck** to pass. *Repo: everything depends
on `wait-for-it-service` being healthy.*

### Healthcheck
A command Compose/K8s runs to decide if a container is *actually ready* (not just running).
*Repo: `db` uses `pg_isready`; the gate uses `nc -z db 5432 && curl unleash/health`.*

### OCI (Open Container Initiative)
The open standards body defining the **Image Spec** (what an image is) and **Runtime Spec**
(how a container is run). Why images aren't Docker-locked — containerd, Podman, etc. all comply.

### modd
A file-watching live-reload runner baked into the dev image; restarts `/server` when the
binary changes. *Repo: `Dockerfile.development` `no-op` stage `ENTRYPOINT ["modd"]`.*

### Hot-swap (local reload)
Copying a freshly built binary into a *running* container instead of rebuilding the image.
*Repo: `run.bash` → `docker cp ../build/server local-$service-1:/server`.*

---

### kind — Kubernetes IN Docker *(Part 2)*
A tool that runs a real Kubernetes cluster inside Docker containers — for local K8s dev/testing.
*Repo: `sk.bash` targets kube-context `kind-kind`.*

### Skaffold *(Part 2)*
A CLI that automates the build → render → deploy loop for Kubernetes apps. *Repo:
`skaffold.*.yaml` + `deployments/sk.bash`.*

### render (Skaffold/Helm) *(Part 2)*
Producing final Kubernetes manifests from templates + values, stamping in built image tags,
without deploying. `skaffold render`.

### env × org matrix *(Part 2)*
This repo's config-organising principle: environment (`local/stag/uat/dorp/prod/trial`) ×
organisation/tenant (`manabie/jprep/tokyo/...`) → namespace `{env}-{org}-backend`, with a
`{env}-{org}-values.yaml` per pair.

### Namespace (Kubernetes) *(Part 2)*
A virtual cluster partition. *Repo: `local-manabie-backend`.* (Not to be confused with a *Linux*
namespace, the container-isolation primitive above — same word, different layer.)