Describe the entrypoint wrapper-script pattern used by images such as the official Postgres image: what work belongs in that script, how it is wired up in the Dockerfile, and why the script must end with `exec "$@"`?

## The shape of the pattern ``` COPY --chmod=755 docker-entrypoint.sh /usr/local/bin/ ENTRYPOINT ["docker-entrypoint.sh"] CMD ["postgres"] ``` Because the runtime concatenates Entrypoint and Cmd, the container's actual argument vector is `docker-entrypoint.sh postgres`. The script therefore receives the intended command as its positional parameters — and if a user runs `docker run img postgres -c max_connections=200`, it receives that instead. The script is a *decorator* around an unknown command, not a replacement for it. ## Why not just do the work in the Dockerfile? Because it depends on runtime inputs that do not exist at build time: environment variables, mounted volumes, secrets, the identity of the host. A config file rendered at build time bakes one environment into the image and breaks the promise that the same artifact ships to every stage. Anything that *is* known at build time — installing packages, compiling, copying static config — belongs in a layer, where it is cached and auditable. A wrapper script that installs packages on every boot is a defect: it slows start-up, needs network at run time, and makes containers non-identical. ## What legitimately belongs in the script - **Config templating.** Substitute environment variables into a config file (`envsubst`, `sed`, or the app's own templating) before the app reads it. - **First-run initialisation.** Databases use a marker file on the data volume: if it is absent, create the cluster, run the seed scripts in `/docker-entrypoint-initdb.d`, then continue; if present, skip straight to start-up. This makes the container idempotent across restarts. - **Volume permission repair.** A bind-mounted host directory arrives with host ownership; the script `chown`s it to the runtime user before dropping privileges. - **Privilege drop.** If the setup genuinely needs root, finish with `exec gosu appuser "$@"` (or `su-exec` on Alpine) instead of `su`/`sudo`, which fork and reintroduce an intermediate PID 1. - **Fail-fast validation.** Check required variables and exit non-zero with a clear message rather than letting the app fail obscurely three seconds later. - **Convenience dispatch.** Many official images check whether the first argument starts with a `-` and, if so, prepend the real binary — so `docker run postgres -c fsync=off` works. Some also pass anything that is not the expected command straight through, so `docker run img bash` still gets you a shell. ## Why `exec "$@"` specifically **`exec`** replaces the shell's process image with the new program, keeping the same PID. Since the script started as PID 1, the application becomes PID 1. That preserves the whole shutdown path: `docker stop` sends SIGTERM to PID 1, the app's handler drains connections and exits, the container stops in milliseconds. Drop the `exec` and the shell stays as PID 1 with the app as its child; the shell does not forward SIGTERM, so every stop takes the full grace period and ends in SIGKILL — dropped requests, corrupt shutdown, ten seconds added to every deploy. **`"$@"`** expands to the script's positional parameters as separate, correctly-quoted words. `$*` collapses them into one string; unquoted `$@` word-splits on spaces, so an argument like `--message=hello world` breaks apart. Only the quoted form round-trips arbitrary arguments faithfully — which is the entire job of a wrapper. ## Operational details that bite - The script must be executable. Prefer `COPY --chmod=755` over a separate `RUN chmod +x`; a non-executable script yields exit code 126. - Line endings must be LF. A script committed from Windows with CRLF has a shebang of `#!/bin/sh\r`, and the kernel reports `no such file or directory` for a file that visibly exists — one of the most confusing container errors there is. - Start the script with `set -e` (and often `set -u`) so a failing setup step aborts the container instead of starting the app in a half-configured state. - Reference the script by a path on `PATH` or an absolute path; a bare relative name interacts badly with WORKDIR changes. - Keep it short and readable. An entrypoint script is code that runs before every observability tool attaches; complexity there is expensive to debug. ## Trade-offs The pattern costs debuggability — inspecting the image now needs `--entrypoint sh` — and adds a place where behaviour hides from the Dockerfile. It buys runtime configurability, idempotent initialisation and a clean single-process shutdown story. For a service image with any first-run or config-rendering needs, that trade is usually right; for a self-contained static binary that reads its own environment, an entrypoint script is pure overhead.