perf(ci): Optimize Docker builds with native ARM runners and improved caching

enko · claude · enko · commit 84719b5a5f2b · 2026-01-19T11:28:58.000+01:00
- Split multi-platform builds to run on native runners (ubuntu-24.04 for amd64,
  ubuntu-24.04-arm for arm64) instead of emulated QEMU builds
- Add registry-based caching alongside GHA cache for better cache hits
- Use architecture-specific cache mount IDs to prevent cache collisions
- Add separate manifest creation job to combine platform-specific images
- Add build dependencies (python3, make, g++) to backend Dockerfile for native
  module compilation (cpu-features, ssh2)

This should significantly reduce ARM64 build times from ~5 minutes (emulated)
to ~30 seconds (native), and improve overall cache hit rates.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -81,25 +81,52 @@ jobs:
             echo "new_release_published=false" >> "$GITHUB_OUTPUT"
           fi
 
-  # Job 3: Build and push Docker images (parallel matrix)
-  docker:
-    name: Build ${{ matrix.image }} Image
+  # Job 3: Build Docker images per platform (native runners for speed)
+  docker-build:
+    name: Build ${{ matrix.image }} (${{ matrix.arch }})
     needs: release
     if: needs.release.outputs.new_release_published == 'true'
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.runner }}
     strategy:
       fail-fast: false
       matrix:
         include:
+          # nginx - amd64
+          - image: nginx
+            dockerfile: docker/Dockerfile.nginx.prod
+            platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          # nginx - arm64
           - image: nginx
             dockerfile: docker/Dockerfile.nginx.prod
-            context: .
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+          # backend - amd64
           - image: backend
             dockerfile: docker/Dockerfile.backend.prod
-            context: .
+            platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          # backend - arm64
+          - image: backend
+            dockerfile: docker/Dockerfile.backend.prod
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+          # sabredav - amd64
+          - image: sabredav
+            dockerfile: docker/Dockerfile.sabredav.prod
+            platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          # sabredav - arm64
           - image: sabredav
             dockerfile: docker/Dockerfile.sabredav.prod
-            context: .
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -122,36 +149,95 @@ jobs:
         with:
           images: ghcr.io/${{ github.repository }}-${{ matrix.image }}
           tags: |
-            type=semver,pattern={{version}},value=v${{ needs.release.outputs.new_release_version }}
-            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.release.outputs.new_release_version }}
-            type=semver,pattern={{major}},value=v${{ needs.release.outputs.new_release_version }}
-            type=raw,value=latest
+            type=raw,value=${{ needs.release.outputs.new_release_version }}-${{ matrix.arch }}
 
       - name: Build and push Docker image
-        id: push
+        id: build
         uses: docker/build-push-action@v6
         with:
-          context: ${{ matrix.context }}
+          context: .
           file: ${{ matrix.dockerfile }}
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha,scope=${{ matrix.image }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.image }}
-          platforms: linux/amd64,linux/arm64
+          platforms: ${{ matrix.platform }}
           provenance: mode=max
           sbom: true
           build-args: ${{ matrix.image == 'nginx' && format('VITE_SENTRY_DSN={0}', secrets.VITE_SENTRY_DSN) || '' }}
+          # Multi-layer caching strategy for maximum cache hits
+          cache-from: |
+            type=gha,scope=${{ matrix.image }}-${{ matrix.arch }}
+            type=registry,ref=ghcr.io/${{ github.repository }}-${{ matrix.image }}:buildcache-${{ matrix.arch }}
+          cache-to: |
+            type=gha,mode=max,scope=${{ matrix.image }}-${{ matrix.arch }}
+            type=registry,ref=ghcr.io/${{ github.repository }}-${{ matrix.image }}:buildcache-${{ matrix.arch }},mode=max
+
+  # Job 4: Create and push multi-arch manifests
+  docker-manifest:
+    name: Create ${{ matrix.image }} Manifest
+    needs: [release, docker-build]
+    if: needs.release.outputs.new_release_published == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - nginx
+          - backend
+          - sabredav
+    steps:
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push manifest
+        env:
+          VERSION: ${{ needs.release.outputs.new_release_version }}
+          IMAGE: ghcr.io/${{ github.repository }}-${{ matrix.image }}
+        run: |
+          # Create manifest for version tag
+          docker manifest create ${IMAGE}:${VERSION} \
+            ${IMAGE}:${VERSION}-amd64 \
+            ${IMAGE}:${VERSION}-arm64
+
+          # Annotate with architecture info
+          docker manifest annotate ${IMAGE}:${VERSION} ${IMAGE}:${VERSION}-amd64 --arch amd64
+          docker manifest annotate ${IMAGE}:${VERSION} ${IMAGE}:${VERSION}-arm64 --arch arm64
+
+          # Push version manifest
+          docker manifest push ${IMAGE}:${VERSION}
+
+          # Create and push additional tags
+          for TAG in "${VERSION%.*}" "${VERSION%%.*}" "latest"; do
+            docker manifest create ${IMAGE}:${TAG} \
+              ${IMAGE}:${VERSION}-amd64 \
+              ${IMAGE}:${VERSION}-arm64
+            docker manifest annotate ${IMAGE}:${TAG} ${IMAGE}:${VERSION}-amd64 --arch amd64
+            docker manifest annotate ${IMAGE}:${TAG} ${IMAGE}:${VERSION}-arm64 --arch arm64
+            docker manifest push ${IMAGE}:${TAG}
+          done
+
+      - name: Get manifest digest
+        id: digest
+        env:
+          IMAGE: ghcr.io/${{ github.repository }}-${{ matrix.image }}
+          VERSION: ${{ needs.release.outputs.new_release_version }}
+        run: |
+          DIGEST=$(docker manifest inspect ${IMAGE}:${VERSION} -v | jq -r '.Descriptor.digest')
+          echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
 
       - name: Attest Docker image
         if: ${{ github.event.repository.visibility == 'public' }}
         uses: actions/attest-build-provenance@v2
         with:
           subject-name: ghcr.io/${{ github.repository }}-${{ matrix.image }}
-          subject-digest: ${{ steps.push.outputs.digest }}
+          subject-digest: ${{ steps.digest.outputs.digest }}
           push-to-registry: true
 
-  # Job 4: Build and attach frontend assets
+  # Job 5: Build and attach frontend assets
   assets:
     name: Build Frontend Assets
     needs: release
@@ -216,10 +302,10 @@ jobs:
           tag_name: v${{ needs.release.outputs.new_release_version }}
           files: frontend-${{ needs.release.outputs.new_release_version }}.tar.gz
 
-  # Job 5: Deploy to production server
+  # Job 6: Deploy to production server
   deploy:
     name: Deploy to Production
-    needs: [release, docker]
+    needs: [release, docker-manifest]
     if: needs.release.outputs.new_release_published == 'true'
     runs-on: ubuntu-latest
     steps:
diff --git a/docker/Dockerfile.backend.prod b/docker/Dockerfile.backend.prod
@@ -5,6 +5,16 @@
 # Stage 1: Build dependencies and compile TypeScript
 FROM node:24-bookworm-slim AS builder
 
+# Get target architecture for cache isolation
+ARG TARGETARCH
+
+# Install build dependencies for native modules (cpu-features, ssh2, etc.)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
 RUN corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 
@@ -16,8 +26,8 @@ COPY tsconfig.base.json ./
 COPY apps/backend/package.json ./apps/backend/
 COPY packages/shared/package.json ./packages/shared/
 
-# Install all dependencies with cache mount
-RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
+# Install all dependencies with architecture-specific cache mount
+RUN --mount=type=cache,id=pnpm-${TARGETARCH},target=/root/.local/share/pnpm/store \
     pnpm install --frozen-lockfile
 
 # Copy source code
@@ -33,6 +43,9 @@ RUN pnpm --filter @freundebuch/shared run build && \
 # Stage 2: Production runtime
 FROM node:24-bookworm-slim AS production
 
+# Get target architecture for cache isolation
+ARG TARGETARCH
+
 RUN corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 
@@ -41,8 +54,8 @@ COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
 COPY apps/backend/package.json ./apps/backend/
 COPY packages/shared/package.json ./packages/shared/
 
-# Install production dependencies only
-RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
+# Install production dependencies only with architecture-specific cache mount
+RUN --mount=type=cache,id=pnpm-${TARGETARCH},target=/root/.local/share/pnpm/store \
     pnpm install --frozen-lockfile --prod --ignore-scripts
 
 # Copy built artifacts
diff --git a/docker/Dockerfile.nginx.prod b/docker/Dockerfile.nginx.prod
@@ -5,6 +5,9 @@
 # Stage 1: Build frontend
 FROM node:24-bookworm-slim AS builder
 
+# Get target architecture for cache isolation
+ARG TARGETARCH
+
 RUN corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 
@@ -16,8 +19,8 @@ COPY tsconfig.base.json ./
 COPY apps/frontend/package.json ./apps/frontend/
 COPY packages/shared/package.json ./packages/shared/
 
-# Install dependencies with cache mount
-RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
+# Install dependencies with architecture-specific cache mount
+RUN --mount=type=cache,id=pnpm-${TARGETARCH},target=/root/.local/share/pnpm/store \
     pnpm install --frozen-lockfile
 
 # Copy source code
diff --git a/docker/Dockerfile.sabredav.prod b/docker/Dockerfile.sabredav.prod
@@ -5,11 +5,14 @@
 # Stage 1: Install PHP dependencies
 FROM composer:2 AS deps
 
+# Get target architecture for cache isolation
+ARG TARGETARCH
+
 WORKDIR /app
 COPY apps/sabredav/composer.json apps/sabredav/composer.lock* ./
 
-# Install dependencies with cache mount (ignore platform reqs - pdo_pgsql is in runtime)
-RUN --mount=type=cache,id=composer,target=/root/.composer/cache \
+# Install dependencies with architecture-specific cache mount (ignore platform reqs - pdo_pgsql is in runtime)
+RUN --mount=type=cache,id=composer-${TARGETARCH},target=/root/.composer/cache \
     composer install --no-dev --optimize-autoloader --no-interaction --ignore-platform-reqs
 
 # Stage 2: Production PHP-FPM runtime
