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

render-docker

NPX Install

Tags

SKILL.md Content