Fix blank page during rolling updates: asset retry, cache headers, rollout strategy, optional sticky sessions

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Jonas Leder 2026-11-16 21:47:35 +01:00
commit 3497653c2c
9 changed files with 66 additions and 2 deletions

View file

@ -20,9 +20,20 @@ server {
proxy_buffering off; # MCP answers are event streams
}
# Hashed build output never changes under the same name. A missing file must be a real 404 (not index.html),
# so the page can notice that it got a stale index.html during a rolling update (see public/boot.js).
# "expires" instead of add_header, so the security headers above still apply.
location /assets/ {
root /usr/share/nginx/html;
expires 1y;
try_files $uri =404;
}
# index.html, sw.js and the manifest must be revalidated on every load, or clients keep a stale entry point.
location / {
root /usr/share/nginx/html;
index index.html;
root /usr/share/nginx/html;
index index.html;
expires -1;
try_files $uri $uri/ /index.html;
}
}

View file

@ -8,6 +8,9 @@ metadata:
app.kubernetes.io/component: backend
spec:
replicas: {{ .Values.replicaCount }}
strategy:
type: RollingUpdate
{{- toYaml .Values.strategy | nindent 4 }}
selector:
matchLabels:
{{- include "pager.selector" (dict "root" . "component" "backend") | nindent 6 }}

View file

@ -7,6 +7,9 @@ metadata:
app.kubernetes.io/component: frontend
spec:
replicas: {{ .Values.replicaCount }}
strategy:
type: RollingUpdate
{{- toYaml .Values.strategy | nindent 4 }}
selector:
matchLabels:
{{- include "pager.selector" (dict "root" . "component" "frontend") | nindent 6 }}

View file

@ -24,6 +24,10 @@ metadata:
labels:
{{- include "pager.labels" . | nindent 4 }}
app.kubernetes.io/component: frontend
{{- with .Values.frontend.serviceAnnotations }}
annotations:
{{- toYaml . | nindent 4 }}
{{- end }}
spec:
type: ClusterIP
selector:

View file

@ -1,3 +1,16 @@
# Rolling update: replace pods one at a time without dropping below the desired count.
# During the rollout old and new versions run side by side, see frontend.serviceAnnotations.
strategy:
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
frontend:
# Annotations of the frontend Service. Sticky sessions keep a browser on one pod, so it gets index.html and
# the hashed assets from the same version while pods are replaced. With Traefik:
# traefik.ingress.kubernetes.io/service.sticky.cookie: "true"
serviceAnnotations: {}
# Number of pods per component. SQLite supports only one backend; use postgres or mariadb for more.
replicaCount: 1

View file

@ -28,3 +28,11 @@ Important values:
| `replicaCount` | Needs postgres or mariadb when above 1 |
The ingress sends `/api` straight to the `backend` service and everything else to `frontend` (set `ingress.exposeSwagger=true` to also route `/swagger` to the backend). The backend accepts traffic only from the frontend pods and from the ingress controller namespace (`networkPolicy.ingressControllerNamespaceLabels`, default `traefik`). Run one release per namespace because the service names are fixed. Terminate TLS at the ingress: Web Push needs HTTPS.
## Rolling updates with several replicas
While pods are replaced, old and new frontend versions run side by side and a browser can get `index.html` from one version and a hashed file from the other, which answers 404. Three things handle this:
- The page notices a failed `/assets/…` request and reloads itself (up to 8 times, with a short random delay) until it gets a matching pair. Users see a short flicker instead of a blank page.
- `index.html` is sent with `Cache-Control: no-cache` and hashed assets with a one-year lifetime, so clients never keep a stale entry point. Missing assets are a real 404.
- The chart rolls out one pod at a time (`strategy.rollingUpdate`: `maxUnavailable: 0`, `maxSurge: 1`). To keep a browser on one pod during the rollout, enable sticky sessions on the frontend Service, e.g. for Traefik: `frontend.serviceAnnotations: {"traefik.ingress.kubernetes.io/service.sticky.cookie": "true"}`.

View file

@ -11,6 +11,7 @@
</head>
<body>
<div id="root"></div>
<script src="/boot.js"></script>
<script type="module" src="/src/main.jsx"></script>
</body>
</html>

19
frontend/public/boot.js Normal file
View file

@ -0,0 +1,19 @@
// Self-heals a rolling update: with several frontend pods, index.html can come from a pod of one version
// and /assets/<hash>.js from a pod of another, which answers 404. Reload (a new request may hit a matching
// pod) a few times; main.jsx clears the counter once the app has started. Kept outside the bundle, so it
// is the same in every version.
(function () {
var KEY = 'pager-asset-retry'
function retry() {
var n = 0
try { n = +sessionStorage.getItem(KEY) || 0 } catch (e) {}
if (n >= 8) return
try { sessionStorage.setItem(KEY, n + 1) } catch (e) {}
setTimeout(function () { location.reload() }, 300 + Math.random() * 900)
}
window.addEventListener('error', function (e) {
var t = e.target
if (t && (t.tagName === 'SCRIPT' || t.tagName === 'LINK') && (t.src || t.href || '').indexOf('/assets/') > -1) retry()
}, true)
window.addEventListener('vite:preloadError', retry)
})()

View file

@ -9,3 +9,5 @@ createRoot(document.getElementById('root')).render(
<App />
</BrowserRouter>,
)
try { sessionStorage.removeItem('pager-asset-retry') } catch (e) {} // the app started: see public/boot.js