fix(docker): compose stack starts cold (gh_token secret + correct healthcheck)

RUNNING_LOCALLY.md

@@ -392,8 +392,13 @@ Open the dashboard at http://localhost:5173 — you should see all four jobs lis
 
 A root-level `docker-compose.yml` runs MySQL, the Spring Boot app (built from the Dockerfile), Prometheus, and Grafana together. It targets the `docker` profile, not `local`.
 
+The app image builds from source and pulls the private `batch-job-api` from GitHub Packages, so the build needs a token. Export `GITHUB_TOKEN` (a PAT with `read:packages`) — it is passed to the build as a BuildKit secret and never lands in an image layer:
+
 ```bash
+export GITHUB_TOKEN=<your-pat-with-read:packages>
 DB_PASSWORD=yourpassword docker compose up -d
 ```
 
+If your GitHub username matters for package auth, also `export GITHUB_ACTOR=<your-username>` (defaults to `x-access-token`).
+
 This is useful for a production-like smoke test, but not the recommended path for day-to-day development because it rebuilds the app image on every change.

docker-compose.yml

@@ -18,6 +18,13 @@ services:
     build:
       context: ./fr-batch-service
       dockerfile: Dockerfile
+      # The Dockerfile pulls the private batch-job-api from GitHub Packages, so the
+      # build needs a token. Export GITHUB_TOKEN (a PAT with read:packages) before
+      # `docker compose up`; GITHUB_ACTOR defaults to x-access-token if unset.
+      args:
+        GITHUB_ACTOR: ${GITHUB_ACTOR:-x-access-token}
+      secrets:
+        - gh_token
     ports:
       - "8080:8080"
     environment:
@@ -33,7 +40,9 @@ services:
       mysql:
         condition: service_healthy
     healthcheck:
-      test: ["CMD", "wget", "-qO-", "http://localhost:8080/api/batch-service/actuator/health"]
+      # Not /actuator/health: it is 503 until a plugin is loaded (endless restart
+      # loop on a fresh stack). /jobs/plugins is 200 once the app serves.
+      test: ["CMD", "wget", "-qO-", "http://localhost:8080/api/batch-service/jobs/plugins"]
       interval: 30s
       timeout: 5s
       retries: 3
@@ -78,3 +87,8 @@ volumes:
   plugin-jars:
   prometheus-data:
   grafana-data:
+
+secrets:
+  # Sourced from the GITHUB_TOKEN env var at build time (BuildKit secret).
+  gh_token:
+    environment: GITHUB_TOKEN

fr-batch-service/Dockerfile

@@ -28,8 +28,12 @@ RUN addgroup -S appgroup && adduser -S appuser -G appgroup
 RUN apk add --no-cache wget
 WORKDIR /app
 COPY --from=build /build/target/*.jar app.jar
+# Probe the plugin-listing endpoint, not /actuator/health: the aggregate health
+# is DOWN (503) until at least one plugin is loaded, which would put a fresh
+# container in an endless unhealthy/restart loop. /jobs/plugins returns 200 as
+# soon as the app serves — the same readiness signal used by CI and process-compose.
 HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
-  CMD wget -qO- http://localhost:8080/api/batch-service/actuator/health || exit 1
+  CMD wget -qO- http://localhost:8080/api/batch-service/jobs/plugins || exit 1
 USER appuser
 EXPOSE 8080
 ENTRYPOINT ["java", "-Xmx512m", "-XX:MaxMetaspaceSize=256m", "-jar", "app.jar"]