From daa11cb768a47dfe2a5a1edbbf234ee6d919cd6c Mon Sep 17 00:00:00 2001
From: Beda Schmid <beda@tukutoi.com>
Date: Mon, 2 Mar 2026 16:57:25 -0300
Subject: [PATCH] Harden frontend npm install against transient registry
 timeouts

---
 .env.example                        |  8 ++++----
 doc/operations-and-configuration.md | 14 ++++++++------
 docker-compose.yml                  |  8 ++++----
 frontend/Dockerfile                 |  8 ++++++--
 4 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/.env.example b/.env.example
index 81fdc06..0821016 100644
--- a/.env.example
+++ b/.env.example
@@ -47,10 +47,10 @@ VITE_ALLOWED_HOSTS=
 # Optional frontend build network and npm fetch tuning:
 DOCKER_BUILD_NETWORK=default
 NPM_REGISTRY=https://registry.npmjs.org/
-NPM_FETCH_RETRIES=5
-NPM_FETCH_RETRY_MINTIMEOUT=20000
-NPM_FETCH_RETRY_MAXTIMEOUT=120000
-NPM_FETCH_TIMEOUT=300000
+NPM_FETCH_RETRIES=10
+NPM_FETCH_RETRY_MINTIMEOUT=30000
+NPM_FETCH_RETRY_MAXTIMEOUT=300000
+NPM_FETCH_TIMEOUT=600000
 
 # Production baseline overrides (set explicitly for live deployments):
 # APP_ENV=production
diff --git a/doc/operations-and-configuration.md b/doc/operations-and-configuration.md
index 8947a15..deb4b23 100644
--- a/doc/operations-and-configuration.md
+++ b/doc/operations-and-configuration.md
@@ -45,20 +45,22 @@ docker compose logs -f
 ## Frontend Build Network Resilience
 
 The frontend Dockerfile uses `node:22-slim` by default for improved npm network compatibility on IPv4-only Linux hosts.
+It also uses a BuildKit cache mount for npm package cache reuse across builds.
 
 The frontend image build supports npm fetch tuning through environment-driven compose build args:
 
 - `NPM_REGISTRY` (default `https://registry.npmjs.org/`)
-- `NPM_FETCH_RETRIES` (default `5`)
-- `NPM_FETCH_RETRY_MINTIMEOUT` (default `20000`)
-- `NPM_FETCH_RETRY_MAXTIMEOUT` (default `120000`)
-- `NPM_FETCH_TIMEOUT` (default `300000`)
+- `NPM_FETCH_RETRIES` (default `10`)
+- `NPM_FETCH_RETRY_MINTIMEOUT` (default `30000`)
+- `NPM_FETCH_RETRY_MAXTIMEOUT` (default `300000`)
+- `NPM_FETCH_TIMEOUT` (default `600000`)
 - `DOCKER_BUILD_NETWORK` (default `default`; set to `host` on Linux hosts when bridge-network npm fetches time out)
 
-If frontend dependency downloads fail with npm `ETIMEDOUT` during `docker compose build`, keep defaults first, then try:
+If frontend dependency downloads fail with npm `ETIMEDOUT` during `docker compose build`, prefer cache-preserving rebuild commands first:
 
 ```bash
-DOCKER_BUILD_NETWORK=host docker compose build --no-cache frontend
+docker compose build frontend
+DOCKER_BUILD_NETWORK=host docker compose build frontend
 ```
 
 ## Authentication Model
diff --git a/docker-compose.yml b/docker-compose.yml
index 03c1c45..3ac3a23 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -148,10 +148,10 @@ services:
       args:
         VITE_API_BASE: ${VITE_API_BASE:-}
         NPM_REGISTRY: ${NPM_REGISTRY:-https://registry.npmjs.org/}
-        NPM_FETCH_RETRIES: ${NPM_FETCH_RETRIES:-5}
-        NPM_FETCH_RETRY_MINTIMEOUT: ${NPM_FETCH_RETRY_MINTIMEOUT:-20000}
-        NPM_FETCH_RETRY_MAXTIMEOUT: ${NPM_FETCH_RETRY_MAXTIMEOUT:-120000}
-        NPM_FETCH_TIMEOUT: ${NPM_FETCH_TIMEOUT:-300000}
+        NPM_FETCH_RETRIES: ${NPM_FETCH_RETRIES:-10}
+        NPM_FETCH_RETRY_MINTIMEOUT: ${NPM_FETCH_RETRY_MINTIMEOUT:-30000}
+        NPM_FETCH_RETRY_MAXTIMEOUT: ${NPM_FETCH_RETRY_MAXTIMEOUT:-300000}
+        NPM_FETCH_TIMEOUT: ${NPM_FETCH_TIMEOUT:-600000}
     environment:
       VITE_API_BASE: ${VITE_API_BASE:-}
       CORS_ORIGINS: '${CORS_ORIGINS:-["http://localhost:5173","http://localhost:3000"]}'
diff --git a/frontend/Dockerfile b/frontend/Dockerfile
index 73f152e..7a1f7d9 100644
--- a/frontend/Dockerfile
+++ b/frontend/Dockerfile
@@ -1,3 +1,5 @@
+# syntax=docker/dockerfile:1.7
+
 FROM node:22-slim AS base
 
 ARG NPM_REGISTRY=https://registry.npmjs.org/
@@ -10,12 +12,14 @@ WORKDIR /app
 
 COPY package.json /app/package.json
 COPY package-lock.json /app/package-lock.json
-RUN npm config set registry "${NPM_REGISTRY}" \
+RUN --mount=type=cache,id=dcm-frontend-npm-cache,target=/root/.npm npm config set registry "${NPM_REGISTRY}" \
     && npm config set fetch-retries "${NPM_FETCH_RETRIES}" \
     && npm config set fetch-retry-mintimeout "${NPM_FETCH_RETRY_MINTIMEOUT}" \
     && npm config set fetch-retry-maxtimeout "${NPM_FETCH_RETRY_MAXTIMEOUT}" \
     && npm config set fetch-timeout "${NPM_FETCH_TIMEOUT}" \
-    && NODE_OPTIONS=--dns-result-order=ipv4first npm ci --no-audit \
+    && npm config set prefer-offline true \
+    && npm config set progress false \
+    && NODE_OPTIONS=--dns-result-order=ipv4first npm ci --no-audit --prefer-offline \
     && chown -R node:node /app
 
 COPY --chown=node:node tsconfig.json /app/tsconfig.json