Persist the Nuitka build cache

.dockerignore

@@ -1,4 +1,5 @@
 upstream/HubBackend/.git
+.build-cache
 .venv*
 build
 dist

.gitignore

@@ -1,4 +1,5 @@
 .env
+.build-cache/
 config/config.json
 data/*
 !data/.gitignore

Dockerfile

@@ -1,6 +1,7 @@
 # syntax=docker/dockerfile:1
 
-FROM python:3.12-trixie AS builder
+# Keep the compiler base stable so that runtime-only updates reuse the Nuitka layer.
+FROM python:3.12-trixie@sha256:ef1735ee20f31133880795148379e68f8fe12f4b7a1872075477567f022edc1f AS builder
 
 WORKDIR /build
 

README.md

@@ -76,6 +76,16 @@ docker compose up -d
 docker compose ps
 ```
 
+The backend build exports its complete BuildKit cache to
+`.build-cache/backend`. This directory includes the intermediate Nuitka build
+layers. Keep it to reuse the compiled result after Docker removes its internal
+build cache. The directory can be large and is excluded from Git and the Docker
+build context.
+
+The Python builder image is pinned to a tested image digest. Update this digest
+deliberately when the compiler environment needs an update. A runtime base
+image update does not invalidate the Nuitka build layer.
+
 By default, the API is available at `http://localhost:17777/api`. Swagger UI is
 available at `http://localhost:17777/api/doc`.
 The default bind address is suitable for a reverse proxy on the Docker host.
@@ -108,7 +118,7 @@ Update the backend source code. Then, rebuild the containers:
 
 ```bash
 git -C upstream/HubBackend pull --ff-only
-docker compose build
+docker compose build backend
 docker compose up -d
 ```
 

compose.yaml

@@ -55,6 +55,10 @@ services:
   backend:
     build:
       context: .
+      cache_from:
+        - type=local,src=.build-cache/backend
+      cache_to:
+        - type=local,dest=.build-cache/backend,mode=max
     restart: unless-stopped
     environment:
       TRUST_HOST_PROXY: "1"