Harden frontend Docker npm fetch resilience

.env.example

@@ -41,6 +41,14 @@ PUBLIC_BASE_URL=http://localhost:8000
 CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]
 VITE_API_BASE=
 
+# 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
+
 # Production baseline overrides (set explicitly for live deployments):
 # APP_ENV=production
 # HOST_BIND_IP=127.0.0.1

doc/operations-and-configuration.md

@@ -42,6 +42,23 @@ Tail logs:
 docker compose logs -f
 ```
 
+## Frontend Build Network Resilience
+
+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`)
+- `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:
+
+```bash
+DOCKER_BUILD_NETWORK=host docker compose build --no-cache frontend
+```
+
 ## Authentication Model
 
 - Legacy shared build-time frontend token behavior was removed.

docker-compose.yml

@@ -134,6 +134,13 @@ services:
   frontend:
     build:
       context: ./frontend
+      network: ${DOCKER_BUILD_NETWORK:-default}
+      args:
+        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}
     environment:
       VITE_API_BASE: ${VITE_API_BASE:-}
     ports:

frontend/Dockerfile

@@ -1,10 +1,21 @@
 FROM node:22-alpine
 
+ARG NPM_REGISTRY=https://registry.npmjs.org/
+ARG NPM_FETCH_RETRIES=5
+ARG NPM_FETCH_RETRY_MINTIMEOUT=20000
+ARG NPM_FETCH_RETRY_MAXTIMEOUT=120000
+ARG NPM_FETCH_TIMEOUT=300000
+
 WORKDIR /app
 
 COPY package.json /app/package.json
 COPY package-lock.json /app/package-lock.json
-RUN npm ci
+RUN 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
 RUN chown -R node:node /app
 
 COPY --chown=node:node tsconfig.json /app/tsconfig.json