niklas‑stephan.de

Docker compose command vs entrypoint gotchas

Last updated 05/11/2026 · migrated-from-outline, docker

.

Reusable gotchas hit while adding containerized services to this server.

command: only replaces the image CMD, never the ENTRYPOINT (the usual trap: repeating the binary)

Compose spec: command (list or string form) overrides the image’s CMD; only entrypoint: overrides the ENTRYPOINT (checked against compose-spec spec.md, 2026-10-14). An earlier version of this note claimed a list-form command: replaces the ENTRYPOINT - that mechanism is wrong; the symptom below was real, the explanation was not.

Concrete failure seen with ghcr.io/anomalyco/opencode (ENTRYPOINT ["opencode"], CMD null):

  • ❌ command: ["opencode", "serve", ...] -> the container runs opencode opencode serve ... (CMD is appended to the entrypoint) -> prints CLI help and crash-loops.
  • ✅ command: ["serve", "--hostname", "0.0.0.0", "--port", "4096"] (or the string form) -> runs opencode serve --hostname 0.0.0.0 --port 4096.

Rule of thumb: check the image’s entrypoint first (docker image inspect IMG --format 'ENTRYPOINT={{json .Config.Entrypoint}} CMD={{json .Config.Cmd}}'). If it already contains the binary, pass only the args in command: (list or string form both work), never the binary name again.

How to verify a Traefik-fronted service is actually routed (not just “up”)

docker ps showing “Up” only proves the container runs — not that Traefik matched the router. A reliable end-to-end check:

curl -sSI https://<host>/
  • If the response carries an x-authentik-id: header (or is an authentik login page), authentik forward-auth ran → the router + middleware chain works.
  • The app may legitimately return 404 for / on a SPA; that’s fine as long as it’s the app answering, not Traefik’s default/catch-all.

(Archived) opencode v2 specifics — all instances removed 2026-10-15/16

The failure above came from ghcr.io/anomalyco/opencode (ENTRYPOINT ["opencode"], CMD null; serve --hostname 0.0.0.0 --port 4096, data in /root/.local/share/opencode). Only relevant if OpenCode is ever redeployed; history in always-on-agent-eval-2026-10 (archive).

Source: Wiki.js