From da42377147ac9e90d5f39678388fed81a06957d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Wed, 8 Apr 2026 08:38:50 +0200
Subject: [PATCH] fix: Docker multi-stage build missing DENO_DIR copy

The multi-stage build example didn't copy DENO_DIR from the builder stage,
causing dependencies to be re-downloaded at runtime. Also improved layer
caching by copying config files before source code in both examples.

Closes #2935

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 runtime/reference/docker.md | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/runtime/reference/docker.md b/runtime/reference/docker.md
index 9f057690f..19a221328 100644
--- a/runtime/reference/docker.md
+++ b/runtime/reference/docker.md
@@ -14,13 +14,14 @@ To use the official image, create a `Dockerfile` in your project directory:
 ```dockerfile
 FROM denoland/deno:latest
 
-# Create working directory
 WORKDIR /app
 
-# Copy source
-COPY . .
+# Cache dependencies by copying config files first
+COPY deno.json deno.lock ./
+RUN deno install
 
-# Install dependencies (use just `deno install` if deno.json has imports)
+# Copy source and install entrypoint
+COPY . .
 RUN deno install --entrypoint main.ts
 
 # Run the app
@@ -37,17 +38,27 @@ For smaller production images:
 # Build stage
 FROM denoland/deno:latest AS builder
 WORKDIR /app
+
+# Cache dependencies by copying config files first
+COPY deno.json deno.lock ./
+RUN deno install
+
+# Then copy source and install entrypoint
 COPY . .
-# Install dependencies (use just `deno install` if deno.json has imports)
 RUN deno install --entrypoint main.ts
 
 # Production stage
 FROM denoland/deno:latest
 WORKDIR /app
 COPY --from=builder /app .
+COPY --from=builder /deno-dir /deno-dir
 CMD ["deno", "run", "--allow-net", "main.ts"]
 ```
 
+The `DENO_DIR` (which defaults to `/deno-dir/` in the official Docker image)
+contains cached dependencies from `deno install`. Copying it to the production
+stage ensures dependencies don't need to be re-downloaded at runtime.
+
 #### Permission Flags
 
 Specify required permissions explicitly: