openbox-fe

Purpose

openbox-fe is the web frontend for the OpenBox platform. Single-page app (SPA) served as static assets from a Node.js server. Talks exclusively to openbox-backend — never directly to core, guardrails, or Keycloak.

Plane: Control plane (client-side).

Ports & endpoints

Port	Protocol	Purpose	Exposed via
3000	HTTP	SPA + Node server	Istio Gateway / ALB / NGINX Ingress
3000/health	HTTP	Liveness	K8s kubelet

Serves the SPA at /. Redirects unauthenticated requests to /auth/login (Keycloak).

Runtime

Property	Value
Container count per pod	1
Resource requests	200m CPU / 512 Mi RAM
Resource limits	500m CPU / 1 Gi RAM
HPA min → max replicas	2 → 6 (target CPU 60%)
Node placement	General-purpose CPU pool
StatefulSet?	No — stateless Deployment

Very light service. HPA tuning matters less than backend/core since compute is minimal.

Configuration

Chart values keys (top-level openbox-fe.*)

Full reference: values-reference. Common overrides:

Key	Purpose
image.repository / image.tag	Container image
replicaCount / autoscaling.*	Static / HPA
env.API_URL	Points at openbox-backend — usually cluster-internal Service DNS
env.KEYCLOAK_URL	For SPA-side OIDC flows (public URL, not cluster-internal)
service.type / service.port	For direct debugging (NodePort in local PoC)

Runtime env vars

• API_URL — public URL of openbox-backend (behind ingress), NOT cluster DNS (SPA runs in user's browser)
• KEYCLOAK_URL — public Keycloak URL for OIDC redirects
• NODE_ENV=production

Dependencies

Downstream

Target	Protocol	Purpose
openbox-backend (via ingress or direct)	HTTPS	All API calls
Keycloak (SPA-side)	HTTPS OIDC	User login redirect

No direct calls to core / guardrails / OPA. All backend-mediated.

Upstream

• End users (via browser) — HTTPS through ingress

Deployment guidelines

Prod

• autoscaling.minReplicas: 2 for HA
• Serve behind CDN if latency-sensitive to global users (customer-side decision — see AWS integration surface non-goals)
• Pin image.tag and NODE_ENV=production (chart default)
• If using ALB Ingress Controller, add annotation for HTTP → HTTPS redirect

Local PoC

• autoscaling.minReplicas: 1, maxReplicas: 1
• service.type: NodePort for direct minikube service access

Troubleshooting

Blank page on load → Wrong API_URL env — SPA can't reach backend. Open browser DevTools → Network tab; look for failed requests to backend. Fix values-side.

Redirects to Keycloak but never returns → Keycloak client's redirect_uri mismatch. Log into Keycloak admin → Realm openbox → Clients → openbox-fe → check Valid redirect URIs includes your FE domain.

Frontend returns 200 but shows "Backend unreachable" → API_URL points at cluster-internal DNS (openbox-backend.openbox.svc.cluster.local) that browsers can't reach. Change to a public URL routed through your ingress.

Assets 404 (missing CSS / JS files) → Static-asset base path misconfigured. Rare — check the image build if this reproduces across pods.

ImagePullBackOff → Same as any pod: verify image tag exists on registry, verify pull secrets. See S2 troubleshooting → #1.