/docs/knowledge/runtime-workflow.md

Runtime Workflow — Match Dev Runtime to Deploy Runtime

Docker is neither banned nor mandatory. It is an optional, per-workload tool. The question is never "do we like containers?" — it is "does my development runtime match the runtime this code will actually run on, and does my workflow match the platform's official one?"

Principle

Develop on the runtime you deploy to.

A global "everything in Docker" mandate fails for edge runtimes and native apps; a global "no Docker" mandate fails for GPU work and resident container workloads. Decide per workload.

Workload matrix

Deploy target / workload	Local development	Why
Cloudflare Workers / edge (incl. Next.js on OpenNext)	Host-native (pnpm dev / wrangler dev / OpenNext preview)	The official flow (below) never touches Docker; running workerd inside Docker on macOS is VM-in-VM and unstable
Native desktop (macOS / Swift / Tauri / Rust CLI)	Host (cargo, xcodebuild, ...)	Nothing is gained by containerizing; GPU, code signing, and Metal require the host
Kubernetes-resident workloads (Node services, Playwright workers, cron daemons)	Docker	The deploy target is a container; matching it locally prevents drift
Python / GPU (CUDA, ML, video processing)	Docker	Host driver injection is the norm; heavy dependencies would pollute the host
Tests (all workloads)	Same runtime as CI (typically containerized)	CI compatibility; prevents host/CI drift
Local Postgres / database stacks	Docker	Local infrastructure stacks belong in containers

When unsure, first answer "what runtime will this code run on in production?", then make dev match it.

The official Cloudflare Workers / Next.js (OpenNext) flow

Common to @opennextjs/cloudflare and Cloudflare's official Next.js on Workers guide (verified against primary sources):

1. Local development: next dev on the host (Node). Calling initOpenNextCloudflareForDev() in next.config gives next dev access to R2/D1/KV bindings.
2. Pre-deploy check: opennextjs-cloudflare preview to preview on workerd.
3. Production: opennextjs-cloudflare deploy.

Docker appears nowhere in the official steps. Do not stand up Docker services for a Workers app.

• OpenNext: https://opennext.js.org/cloudflare
• Cloudflare: https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/

Rules that apply to every workload

• Never bind-mount the host's ./node_modules into a Linux container (use a named volume instead).
• If files are generated by tooling (compose files, generated config), edit them through the generator, not by hand.
• Never commit host-specific absolute paths.

A note on enforcement

Prefer documented rules over hard intercepts. Wrapper scripts that forcibly redirect host commands into containers break the host-native workloads in the matrix above; keep the policy in prose (e.g. your CLAUDE.md) and review it in PRs rather than enforcing it with a binary block.