AGENT SKILL

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

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: 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):

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

04 同仓库更多 Skills

kael-odin
kael-odin/codex-plugins-zh

android-emulator-qa

Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture.

★ 37
kael-odin
kael-odin/codex-plugins-zh

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.

★ 37
kael-odin
kael-odin/codex-plugins-zh

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`.

★ 37
kael-odin
kael-odin/codex-plugins-zh

render-workflows

搭建、开发、测试和部署 Render Workflows。涵盖首次脚手架搭建(通过 CLI 或手动方式)、SDK 安装(Python 或 TypeScript)、任务模式(重试、子任务、扇出)、本地开发、控制台部署和故障排查。适用于用户首次搭建 Render Workflows、构建工作流服务、添加或修改工作流任务、本地测试工作流或部署到 Render 的场景。

★ 37
kael-odin
kael-odin/codex-plugins-zh

render-web-services

配置 Render web service——端口绑定、TLS、健康检查、自定义域名、自动部署、PR 预览、持久化磁盘及部署生命周期。当用户需要搭建 web service、修复健康检查失败、添加自定义域名、配置零停机部署,或排查端口绑定问题时使用。

★ 37
kael-odin
kael-odin/codex-plugins-zh

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。

★ 37