Simplify application recipes around first-class images
Update the application recipes to use services.<name>.image as the happy path when an upstream image is already runnable. Remove wrapper builds and reconstructed image metadata where Miren can inherit the upstream contract.
This docs change should land after:
- MIR-1696 makes WORKDIR and EXPOSE inheritance work for direct-image deployments.
- MIR-1697 allows recipes to preserve an image entrypoint while replacing its CMD.
Keep a Dockerfile when the recipe genuinely changes the image. The goal is not to make every recipe image-only.
Recipe audit
- Hermes: Replace the wrapper Dockerfile and
[build]section withservices.web.image. Useargs = ["gateway", "run"]so the image’s dispatcher remains its entrypoint. Keepport = 9119because the image does not expose a port. - OpenHands: Verify and pin a currently supported agent-server image. Replace the wrapper Dockerfile and
[build]section withservices.web.image. Keep the upstream entrypoint and omit the explicit port once MIR-1696 inherits its exposed port 8000. - Headscale: Keep the Dockerfile because it copies
config.yamland supplies the CMD missing from the upstream shellless image. Explain why this is a real derived image rather than legacy scaffolding. - Amp runner: Keep the Dockerfile because the recipe installs Amp and supporting tools, then copies its runner script. Make clear that this builds an application rather than wrapping an already-runnable image.
Across the recipes
Add a consistent rule of thumb:
- Prefer
services.<name>.imagewhen the upstream image is runnable as-is. - Add
argswhen its entrypoint is correct but it needs deployment-specific arguments. - Use
commandwhen the complete process needs a shell-based override. - Use a Dockerfile when the deployment adds files or packages, or must repair an incomplete image contract.
Remove stale explanations implying that every third-party image needs a wrapper Dockerfile.
Done when
- Every recipe has been checked against the actual metadata of its selected image.
- Eligible recipes use
services.<name>.imagewithout a wrapper Dockerfile or build context. - Remaining commands, arguments, and ports are intentional and explained.
- Dockerfile-based recipes clearly state what their derived image adds.
- Changed image-backed recipes have been smoke-deployed on a build containing MIR-1696 and MIR-1697.
- The docs lint passes.