feat(docker): enhance multi-architecture and CUDA support in Docker workflows

- Added support for multiple image variants (CPU, CUDA 12.8, CUDA 12.6) in the Docker build workflow.
- Updated Docker Compose configuration to utilize the new SURFSENSE_VARIANT environment variable for selecting image variants.
- Enhanced documentation to clarify usage of backend image variants and their corresponding environment variable settings.

.github/workflows/docker-build.yml

@@ -97,6 +97,12 @@ jobs:
       matrix:
         platform: [linux/amd64, linux/arm64]
         image: [backend, web]
+        variant: [cpu, cuda, cuda126]
+        exclude:
+          - image: web
+            variant: cuda
+          - image: web
+            variant: cuda126
         include:
           - platform: linux/amd64
             suffix: amd64
@@ -114,6 +120,18 @@ jobs:
             context: ./surfsense_web
             file: ./surfsense_web/Dockerfile
             target: runner
+          - variant: cpu
+            tag_suffix: ""
+            use_cuda: "false"
+            cuda_extra: cpu
+          - variant: cuda
+            tag_suffix: "-cuda"
+            use_cuda: "true"
+            cuda_extra: cu128
+          - variant: cuda126
+            tag_suffix: "-cuda126"
+            use_cuda: "true"
+            cuda_extra: cu126
     env:
       REGISTRY_IMAGE: ghcr.io/${{ github.repository_owner }}/${{ matrix.name }}
 
@@ -149,7 +167,7 @@ jobs:
           sudo rm -rf "$AGENT_TOOLSDIRECTORY" || true
           docker system prune -af
 
-      - name: Build and push by digest ${{ matrix.name }} (${{ matrix.suffix }})
+      - name: Build and push by digest ${{ matrix.name }} (${{ matrix.variant }}, ${{ matrix.suffix }})
         id: build
         uses: docker/build-push-action@v7
         with:
@@ -160,10 +178,12 @@ jobs:
           tags: ${{ steps.image.outputs.name }}
           outputs: type=image,push-by-digest=true,name-canonical=true,push=true
           platforms: ${{ matrix.platform }}
-          cache-from: type=gha,scope=${{ matrix.image }}-${{ matrix.suffix }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.image }}-${{ matrix.suffix }}
+          cache-from: type=registry,ref=${{ steps.image.outputs.name }}:buildcache-${{ matrix.variant }}-${{ matrix.suffix }}
+          cache-to: type=registry,ref=${{ steps.image.outputs.name }}:buildcache-${{ matrix.variant }}-${{ matrix.suffix }},mode=max,image-manifest=true,oci-mediatypes=true
           provenance: false
           build-args: |
+            ${{ matrix.image == 'backend' && format('USE_CUDA={0}', matrix.use_cuda) || '' }}
+            ${{ matrix.image == 'backend' && format('CUDA_EXTRA={0}', matrix.cuda_extra) || '' }}
             ${{ matrix.image == 'web' && 'NEXT_PUBLIC_FASTAPI_BACKEND_URL=__NEXT_PUBLIC_FASTAPI_BACKEND_URL__' || '' }}
             ${{ matrix.image == 'web' && 'NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=__NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE__' || '' }}
             ${{ matrix.image == 'web' && 'NEXT_PUBLIC_ETL_SERVICE=__NEXT_PUBLIC_ETL_SERVICE__' || '' }}
@@ -179,7 +199,7 @@ jobs:
       - name: Upload digest
         uses: actions/upload-artifact@v7
         with:
-          name: digests-${{ matrix.image }}-${{ matrix.suffix }}
+          name: digests-${{ matrix.image }}-${{ matrix.variant }}-${{ matrix.suffix }}
           path: /tmp/digests/*
           if-no-files-found: error
           retention-days: 1
@@ -187,7 +207,7 @@ jobs:
   create_manifest:
     runs-on: ubuntu-latest
     needs: [tag_release, build]
-    if: always() && needs.build.result == 'success'
+    if: ${{ !cancelled() }}
     permissions:
       packages: write
       contents: read
@@ -197,8 +217,20 @@ jobs:
         include:
           - name: surfsense-backend
             image: backend
+            variant: cpu
+            tag_suffix: ""
+          - name: surfsense-backend
+            image: backend
+            variant: cuda
+            tag_suffix: "-cuda"
+          - name: surfsense-backend
+            image: backend
+            variant: cuda126
+            tag_suffix: "-cuda126"
           - name: surfsense-web
             image: web
+            variant: cpu
+            tag_suffix: ""
     env:
       REGISTRY_IMAGE: ghcr.io/${{ github.repository_owner }}/${{ matrix.name }}
 
@@ -207,22 +239,33 @@ jobs:
         id: image
         run: echo "name=${REGISTRY_IMAGE,,}" >> $GITHUB_OUTPUT
 
-      - name: Download amd64 digest
+      - name: Download digests
+        id: download
         uses: actions/download-artifact@v8
         with:
-          name: digests-${{ matrix.image }}-amd64
+          pattern: digests-${{ matrix.image }}-${{ matrix.variant }}-*
           path: /tmp/digests
+          merge-multiple: true
+        continue-on-error: true
 
-      - name: Download arm64 digest
-        uses: actions/download-artifact@v8
-        with:
-          name: digests-${{ matrix.image }}-arm64
-          path: /tmp/digests
+      - name: Check digests
+        id: check
+        run: |
+          count=$(find /tmp/digests -type f 2>/dev/null | wc -l | tr -d ' ')
+          echo "digest_count=$count" >> $GITHUB_OUTPUT
+          if [ "$count" -lt 2 ]; then
+            echo "::warning::${{ matrix.variant }}: $count/2 digests, skipping merge"
+            echo "skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
 
       - name: Set up Docker Buildx
+        if: steps.check.outputs.skip != 'true'
         uses: docker/setup-buildx-action@v4
 
       - name: Login to GitHub Container Registry
+        if: steps.check.outputs.skip != 'true'
         uses: docker/login-action@v4
         with:
           registry: ghcr.io
@@ -230,6 +273,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Compute app version
+        if: steps.check.outputs.skip != 'true'
         id: appver
         run: |
           VERSION_TAG="${{ needs.tag_release.outputs.new_tag }}"
@@ -241,6 +285,7 @@ jobs:
           echo "app_version=$APP_VERSION" >> $GITHUB_OUTPUT
 
       - name: Docker meta
+        if: steps.check.outputs.skip != 'true'
         id: meta
         uses: docker/metadata-action@v6
         with:
@@ -252,18 +297,22 @@ jobs:
             type=sha,prefix=git-
           flavor: |
             latest=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) || github.event.inputs.branch == github.event.repository.default_branch }}
+            ${{ matrix.tag_suffix != '' && format('suffix={0},onlatest=true', matrix.tag_suffix) || '' }}
 
       - name: Create manifest list and push
+        if: steps.check.outputs.skip != 'true'
         working-directory: /tmp/digests
         run: |
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             $(printf '${{ steps.image.outputs.name }}@sha256:%s ' *)
       - name: Inspect image
+        if: steps.check.outputs.skip != 'true'
         run: |
           docker buildx imagetools inspect ${{ steps.image.outputs.name }}:${{ steps.meta.outputs.version }}
 
       - name: Summary
+        if: steps.check.outputs.skip != 'true'
         run: | 
           echo "Multi-arch manifest created for ${{ matrix.name }}!"
           echo "Tags: $(jq -cr '.tags | join(", ")' <<< "$DOCKER_METADATA_OUTPUT_JSON")"