render-docker
在 Render 上构建并部署 Docker 容器——Dockerfile、多阶段构建、Blueprint 的 Docker 字段、私有 registry、层缓存及平台约束。当用户提到 Docker、Dockerfile、容器镜像、多阶段构建、容器 registry、GHCR、ECR、BuildKit、dockerContext、runtime docker 或 image,或要优化 Render 上的 Docker 构建时使用。
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 37
- Forks
- 1
01 前言 Front Matter
- name
- render-docker
- license
- MIT
- metadata
- { "author": "Render", "version": "1.0.0", "category": "deployment" }
- description
- 在 Render 上构建并部署 Docker 容器——Dockerfile、多阶段构建、Blueprint 的 Docker 字段、私有 registry、层缓存及平台约束。当用户提到 Docker、Dockerfile、容器镜像、多阶段构建、容器 registry、GHCR、ECR、BuildKit、dockerContext、runtime docker 或 image,或要优化 Render 上的 Docker 构建时使用。
- compatibility
- Any Render compute service (web, private, worker, cron) with runtime: docker or runtime: image.
02 资源文件 4
- 参考文档agents/openai.yaml208 B
- 参考文档references/dockerfile-patterns.md5.5 KB
- 参考文档references/optimization-guide.md3.3 KB
- 参考文档references/registry-setup.md3.1 KB
03 SKILL.md 正文
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: dockervsruntime: imagein 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 usingdockerfilePath,dockerContext, and optionaldockerCommand(overrides imageCMD).runtime: image: Render pullsimage.url; no repo-based image build. Pair withregistryCredentialwhen 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):
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 thanARG.
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
latestcan 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 setsPORT). - 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
.dockerignorethat excludesnode_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'(preferexecso 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.yamlschema, wiring, and validation - render-web-services — Web service behavior, health checks, and HTTP edge cases
04 同仓库更多 Skills
android-emulator-qa
Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture.
supabase-postgres-best-practices
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
sentry
Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`.
render-workflows
搭建、开发、测试和部署 Render Workflows。涵盖首次脚手架搭建(通过 CLI 或手动方式)、SDK 安装(Python 或 TypeScript)、任务模式(重试、子任务、扇出)、本地开发、控制台部署和故障排查。适用于用户首次搭建 Render Workflows、构建工作流服务、添加或修改工作流任务、本地测试工作流或部署到 Render 的场景。
render-web-services
配置 Render web service——端口绑定、TLS、健康检查、自定义域名、自动部署、PR 预览、持久化磁盘及部署生命周期。当用户需要搭建 web service、修复健康检查失败、添加自定义域名、配置零停机部署,或排查端口绑定问题时使用。
render-static-sites
在 Render 全球 CDN 上部署并配置静态站点——构建命令、发布路径、SPA 路由、重定向、自定义 header 及 PR 预览。当用户需要部署静态站点、搭建 React/Vue/Hugo/Gatsby 前端、配置 SPA 回退路由、添加重定向规则、自定义响应 header,或在静态站点与 web service 之间为前端做选择时使用。触发词:static site、CDN、SPA、single-page app、React deploy、Vue deploy、Hugo、Gatsby、Docusaurus、Jekyll、staticPublishPath。