render-docker

# Render Docker Deployments Render uses **BuildKit** for Docker builds. All compute service types that support custom runtimes can use **`runtime: docker`** (build from a Dockerfile in the repo) or **`runtime: image`** (pull a prebuilt image; no Dockerfile build on Render). Deeper patterns and copy-paste templates live under `references/`. ## When to Use - Authoring or debugging a **Dockerfile** for a Render service - Choosing **`runtime: docker`** vs **`runtime: image`** in a Blueprint - Wiring **private base images** or **prebuilt images** with registry credentials - **Multi-stage builds**, **build args**, **secrets**, and **layer caching** - **Performance** and **security** hardening of container images on Render For full Blueprint authoring, see **render-blueprints**. For end-to-end deploy flows, see **render-deploy**. ## Render Docker Builds - **BuildKit** is used for Docker builds on Render. - **`runtime: docker`**: Render builds an image from your repo using `dockerfilePath`, `dockerContext`, and optional `dockerCommand` (overrides image `CMD`). - **`runtime: image`**: Render pulls **`image.url`**; no repo-based image build. Pair with **`registryCredential`** when the registry is private. ## Blueprint Configuration | Field | Role | |-------|------| | `dockerfilePath` | Path to the Dockerfile (default `./Dockerfile`) | | `dockerContext` | Build context directory (what is sent to the daemon) | | `dockerCommand` | Overrides the container `CMD` after the image is built | | `image.url` | Image reference for `runtime: image` (registry/repo:tag or digest) | | `registryCredential` | Auth for private pulls; often `fromRegistryCreds` → Dashboard-stored credential | Example sketch (values illustrative): ```yaml services: - type: web name: api runtime: docker region: oregon plan: starter dockerfilePath: ./Dockerfile dockerContext: . dockerCommand: node server.js envVars: - key: PORT value: 10000 ``` For `runtime: image`, set `image.url` and, if needed, `registryCredential` per **Registry Configuration** below. ## Multi-Stage Builds **Recommended for production.** Use a **builder** stage for compilation and dependency installation, and a minimal **runner** stage that only copies artifacts and runtime files. Benefits: - Smaller images and faster pulls - Fewer tools and secrets in the final image (smaller attack surface) - Clear separation between build-time and run-time dependencies See `references/dockerfile-patterns.md` for language-specific templates. ## Build Args vs Secrets **Critical:** **Never pass secrets via `ARG`.** Build arguments are stored in image **layers** and can be recovered from the image history or intermediate layers. - Prefer **runtime environment variables** (Render **env vars** / secret files) for application secrets. - For **build-time** secrets (e.g. private package feeds), use **Docker BuildKit secret mounts** (`RUN --mount=type=secret,...`) rather than `ARG`. Treat anything sensitive as **runtime** or **BuildKit secret mount**, not as a build arg. ## Registry Configuration Private **base images** (for `runtime: docker`) or **prebuilt images** (`runtime: image`) need authentication: - Store credentials in the Render Dashboard under **Registry Credentials**. - In Blueprint, reference them with **`registryCredential.fromRegistryCreds.name`** (match the Dashboard name). Supports common registries (Docker Hub, GHCR, ECR, Google Artifact Registry, and others). Step-by-step per provider: `references/registry-setup.md`. **Prebuilt image services** do **not** auto-deploy when the tag moves in the registry; trigger a **manual redeploy** or use a **deploy hook** when you publish a new image. ## Layer Caching - Render **caches Docker layers** between builds; **order Dockerfile instructions** so that frequently unchanged layers stay early (see `references/optimization-guide.md`). - **Tags and caching:** mutable tags like **`latest`** can resolve to **stale cached** images. Prefer **immutable** references: **digest** (`repo/image@sha256:...`) or **version pins** (`v1.2.3`). ## Platform Specifics - Render builds **linux/amd64**. Avoid assumptions about other architectures in production images. - **Port binding** matches native services: bind HTTP to **`0.0.0.0:$PORT`** (Render sets `PORT`). - **Health checks** behave like non-Docker web services (`healthCheckPath`, etc.). - **Secret files** from Render appear under **`/etc/secrets/`** — do not rely on repo-root secret paths inside the container unless you copy or mount them explicitly in the image. ## `.dockerignore` and Start Commands - Always maintain a **`.dockerignore`** that excludes **`node_modules`**, **`.git`**, **`.env`**, build artifacts, logs, and OS junk. This shrinks context upload time and avoids leaking local files into layers. Lists and rationale: `references/optimization-guide.md`. - **Custom start command:** if you need multiple shell steps, use a single shell form, e.g. **`/bin/sh -c 'set -e; ./migrate && exec node server.js'`** (prefer **`exec`** so your app receives signals for graceful shutdown). ## References | Document | Contents | |----------|----------| | `references/dockerfile-patterns.md` | Multi-stage templates (Node, Python, Go, Ruby, Rust, static sites) | | `references/registry-setup.md` | Docker Hub, GHCR, ECR, Artifact Registry + Blueprint wiring | | `references/optimization-guide.md` | Layer order, `.dockerignore`, BuildKit cache mounts, debugging | ## Related Skills - **render-deploy** — Deploy flows, Blueprint vs Dashboard, operational steps - **render-blueprints** — Full `render.yaml` schema, wiring, and validation - **render-web-services** — Web service behavior, health checks, and HTTP edge cases