feat: Optimize Docker image caching layers (#1139)

## Summary

This PR improves Docker build caching so that CI builds are faster and
more cache-efficient — both in terms of Docker layer caching and package
download caching.

---

## What changed

### `EssentialCSharp.Web/Dockerfile`
- **Metadata-first COPY pattern**: copies `.slnx`, `.csproj`,
`Directory.*.props`, `global.json`, and `nuget.config` before `dotnet
restore` — restore layer is only invalidated when dependencies change,
not on every source edit
- **Split restore / build / publish**: finer cache granularity; `COPY .
.` no longer busts the restore layer
- **BuildKit cache mounts**: `--mount=type=cache` for both NuGet
packages (`/root/.nuget/packages`) and npm (`/root/.npm`) — skips
re-downloading packages when lockfiles haven't changed
- **Narrowed frontend COPY inputs**: only `vite.config.js`, `src/`, and
`wwwroot/js/` are copied into the frontend stage — backend-only changes
no longer invalidate the npm build layer

### `.github/workflows/PR-Build-And-Test.yml` &
`Build-Test-And-Deploy.yml`
- **Explicit GHA cache scopes**: `essentialcsharpweb-main`,
`essentialcsharpweb-pr`, `essentialcsharpweb-deploy` — prevents
cross-workflow cache contention
- **`reproducible-containers/buildkit-cache-dance`**: bridges BuildKit's
daemon-local cache mounts to GitHub Actions cache. Without this,
`--mount=type=cache` entries are empty on every CI run (fresh ephemeral
runner = fresh BuildKit daemon). With it:
  - `actions/cache` restores host-side cached data for npm and NuGet
- `buildkit-cache-dance` injects that data into BuildKit before the
build
  - After the build, updated cache data is extracted back out and saved

**PR vs main branch policy:**
- PR workflow → `skip-extraction: true` (reads cache, doesn't write
back; avoids polluting canonical cache with feature branches)
- Deploy workflow → `skip-extraction: false` (reads and writes; keeps
the canonical cache warm)

---

## Caching architecture (after this PR)

```
actions/cache ←→ buildkit-cache-dance ←→ BuildKit cache mounts (/root/.nuget, /root/.npm)
     ↕
type=gha layer cache (Docker layer snapshots)
```

Both mechanisms now work end-to-end in CI, not just locally.

Author: BenjaminMichaelis

.dockerignore

@@ -1,3 +1,5 @@
+**/.buildkit-cache
+**/buildkit-cache
 **/.classpath
 **/.dockerignore
 **/.env

.github/workflows/Build-Test-And-Deploy.yml

@@ -62,6 +62,23 @@ jobs:
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
+        id: buildx
+
+      - name: Restore BuildKit cache mounts
+        uses: actions/cache@v5
+        id: buildkit-cache
+        with:
+          path: buildkit-cache
+          key: buildkit-cache-${{ hashFiles('EssentialCSharp.Web/Dockerfile', 'Directory.Packages.props', '**/*.csproj', 'EssentialCSharp.Web/package-lock.json') }}
+          restore-keys: buildkit-cache-
+
+      - name: Inject BuildKit cache mounts
+        uses: reproducible-containers/buildkit-cache-dance@v3
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          dockerfile: EssentialCSharp.Web/Dockerfile
+          cache-dir: buildkit-cache
+          skip-extraction: false
 
       # Only build for dev registry — prod gets the image via az acr import in deploy-production
       - name: Build Container Image
@@ -74,8 +91,8 @@ jobs:
           secrets: |
             "nuget_pat=${{ secrets.AZURE_DEVOPS_PAT }}"
           outputs: type=docker,dest=${{ github.workspace }}/essentialcsharpwebimage.tar
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=essentialcsharpweb-main
+          cache-to: type=gha,mode=max,scope=essentialcsharpweb-main
 
       - name: Upload artifact
         uses: actions/upload-artifact@v7

.github/workflows/PR-Build-And-Test.yml

@@ -82,13 +82,32 @@ jobs:
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
+        id: buildx
+
+      - name: Restore BuildKit cache mounts
+        uses: actions/cache/restore@v5
+        id: buildkit-cache
+        with:
+          path: buildkit-cache
+          key: buildkit-cache-${{ hashFiles('EssentialCSharp.Web/Dockerfile', 'Directory.Packages.props', '**/*.csproj', 'EssentialCSharp.Web/package-lock.json') }}
+          restore-keys: buildkit-cache-
+
+      - name: Inject BuildKit cache mounts
+        uses: reproducible-containers/buildkit-cache-dance@v3
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          dockerfile: EssentialCSharp.Web/Dockerfile
+          cache-dir: buildkit-cache
+          skip-extraction: true
 
       - name: Build Container Image
         uses: docker/build-push-action@v7
         with:
           file: ./EssentialCSharp.Web/Dockerfile
           context: .
           push: false
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: |
+            type=gha,scope=essentialcsharpweb-main
+            type=gha,scope=essentialcsharpweb-pr
+          cache-to: type=gha,mode=max,scope=essentialcsharpweb-pr
           build-args: ACCESS_TO_NUGET_FEED=false

EssentialCSharp.Web/Dockerfile

@@ -8,17 +8,26 @@ EXPOSE 8081
 FROM node:26-bookworm-slim AS frontend-build
 WORKDIR /frontend/EssentialCSharp.Web
 COPY EssentialCSharp.Web/package.json EssentialCSharp.Web/package-lock.json ./
-RUN npm ci
-COPY EssentialCSharp.Web/ ./
+RUN --mount=type=cache,id=essentialcsharp-web-npm,target=/root/.npm \
+    npm ci
+COPY EssentialCSharp.Web/vite.config.js ./vite.config.js
+COPY EssentialCSharp.Web/src ./src
+COPY EssentialCSharp.Web/wwwroot/js ./wwwroot/js
 RUN npm run build
 
 FROM mcr.microsoft.com/dotnet/sdk:10.0.300 AS build
 ARG ACCESS_TO_NUGET_FEED=true
 ENV ACCESS_TO_NUGET_FEED=$ACCESS_TO_NUGET_FEED
 WORKDIR /src
-COPY . .
-COPY --from=frontend-build /frontend/EssentialCSharp.Web/wwwroot/dist ./EssentialCSharp.Web/wwwroot/dist
+COPY EssentialCSharp.Web.slnx ./
+COPY Directory.Build.props Directory.Build.targets Directory.Packages.props global.json nuget.config ./
+COPY EssentialCSharp.Chat.Shared/EssentialCSharp.Chat.Common.csproj ./EssentialCSharp.Chat.Shared/
+COPY EssentialCSharp.Chat.Tests/EssentialCSharp.Chat.Tests.csproj ./EssentialCSharp.Chat.Tests/
+COPY EssentialCSharp.Chat/EssentialCSharp.Chat.csproj ./EssentialCSharp.Chat/
+COPY EssentialCSharp.Web.Tests/EssentialCSharp.Web.Tests.csproj ./EssentialCSharp.Web.Tests/
+COPY EssentialCSharp.Web/EssentialCSharp.Web.csproj ./EssentialCSharp.Web/
 RUN --mount=type=secret,id=nuget_pat,required=false \
+    --mount=type=cache,id=essentialcsharp-web-nuget,target=/root/.nuget/packages \
     if [ "$ACCESS_TO_NUGET_FEED" = "true" ] && [ ! -s /run/secrets/nuget_pat ]; then \
       echo "ERROR: ACCESS_TO_NUGET_FEED=true but nuget_pat secret is missing or empty" >&2; exit 1; \
     fi && \
@@ -28,9 +37,13 @@ RUN --mount=type=secret,id=nuget_pat,required=false \
         "$(cat /run/secrets/nuget_pat)" > /root/.nuget/NuGet/NuGet.Config; \
     fi && \
     dotnet restore "EssentialCSharp.Web.slnx" -p:AccessToNugetFeed=$ACCESS_TO_NUGET_FEED && \
-    dotnet build "EssentialCSharp.Web.slnx" -c Release --no-restore -p:AccessToNugetFeed=$ACCESS_TO_NUGET_FEED -p:ReleaseDateAttribute=True -p:SkipFrontendBuild=true && \
-    dotnet publish "EssentialCSharp.Web.slnx" -c Release -p:PublishDir=/app/publish -p:UseAppHost=false -p:SkipFrontendBuild=true --no-build && \
     rm -f /root/.nuget/NuGet/NuGet.Config
+COPY . .
+COPY --from=frontend-build /frontend/EssentialCSharp.Web/wwwroot/dist ./EssentialCSharp.Web/wwwroot/dist
+RUN --mount=type=cache,id=essentialcsharp-web-nuget,target=/root/.nuget/packages \
+    dotnet build "EssentialCSharp.Web.slnx" -c Release --no-restore -p:AccessToNugetFeed=$ACCESS_TO_NUGET_FEED -p:ReleaseDateAttribute=True -p:SkipFrontendBuild=true
+RUN --mount=type=cache,id=essentialcsharp-web-nuget,target=/root/.nuget/packages \
+    dotnet publish "EssentialCSharp.Web.slnx" -c Release -p:PublishDir=/app/publish -p:UseAppHost=false -p:SkipFrontendBuild=true --no-build
 
 FROM base AS final
 WORKDIR /app