feat: create developer-portal-fe helm chart

[Claude]

Implements a standalone Helm chart for the API7 Developer Portal Frontend (Next.js app), separating it from the api7 umbrella chart. The frontend has its own PostgreSQL database for Better Auth user management and connects to the existing Portal API backend via URL + token.

Chart Structure

• Chart metadata: developer-portal-fe v0.1.0 (appVersion 0.5.7) with PostgreSQL 12.12.10 dependency
• Templates: Following api7 chart conventions with deployment, service, ingress, serviceaccount, configmap, and secret
• Helper functions: Standard naming, labeling, and template rendering utilities

Configuration Strategy

Environment variables injected via Kubernetes Secrets, referenced in config.yaml using ${VAR} placeholders:

# configmap.yaml - config file with placeholders
portal:
  url: "https://api7-developer-portal:4321"
  token: ${PORTAL_TOKEN}
db:
  url: ${DB_URL}
auth:
  secret: ${AUTH_SECRET}

# deployment.yaml - secrets mounted as env vars
env:
  - name: PORTAL_TOKEN
    valueFrom:
      secretKeyRef:
        name: <chart-or-existing-secret>
        key: portal-token

Key Features

• Secrets management: Supports both inline values and independent existingSecret references for portal token, DB URL, and auth secret
• PostgreSQL: Optional built-in PostgreSQL via bitnami subchart with easy external DB configuration
• TLS control: tlsRejectUnauthorized flag for development with self-signed certificates
• Health probes: HTTP checks on / (configurable) with configurable delays
• Ingress: Multi-version Kubernetes support (1.14+ to 1.19+)
• Flexibility: Extra env vars, volumes, topology spread constraints, resource overrides

Architecture

┌─────────────────────────────┐
│  api7 umbrella chart         │
│  ┌──────────────┐           │
│  │ Portal API   │           │
│  │ (backend)    │           │
│  │ :4321        │◄──────────┼─── portal.url + token
│  └──────────────┘           │
│  PostgreSQL (api7ee)        │
└─────────────────────────────┘

┌─────────────────────────────┐
│ developer-portal-fe chart   │
│  ┌──────────────┐           │
│  │ Frontend FE  │           │
│  │ (Next.js)    │           │
│  │ :3001        │           │
│  └──────────────┘           │
│  PostgreSQL (Better Auth)   │
└─────────────────────────────┘

Fixes Applied (post initial PR)

1. Health probe path: Changed from /healthz to / — the portal-fe app has no /healthz endpoint
2. PostgreSQL image: Removed override to docker.io/postgres:16, using bitnami default image
3. Secret management: Fixed independent existingSecret support — previously setting portal.existingSecret would break DB and auth secret refs

Deployment Verified

Chart deployed and validated on a kind cluster with API7 EE v3.9.7. All components running successfully.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ nic-6443
❌ Claude
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[nic-6443]

Deployment Test Results (kind cluster, api7 namespace)

Environment

• Existing API7 EE v3.9.7 running in api7 namespace (kind cluster)
• Portal token created for the default portal instance
• Chart installed with: helm install portal-fe . --namespace api7

Results

Component	Status	Details
helm lint	✅ Pass	No errors, 1 info (icon recommended)
helm install	✅ Pass	Release deployed successfully
PostgreSQL StatefulSet	✅ Running	Pod started, DB initialized and accepting connections
Portal FE Deployment	❌ CrashLoopBackOff	See issues below

Issues Found

1. 🔴 CRITICAL: Health check path /healthz returns 404

The liveness and readiness probes in deployment.yaml use /healthz, but the portal-fe app (api7/api7-ee-developer-portal-fe:v0.5.7) does not have a /healthz route.

Symptoms:

Warning  Unhealthy  kubelet  Readiness probe failed: HTTP probe failed with statuscode: 404
Warning  Unhealthy  kubelet  Liveness probe failed: HTTP probe failed with statuscode: 404

The app starts successfully (preflight checks pass, Next.js server starts), but Kubernetes kills it because the liveness probe keeps failing with 404.

Evidence:

# / returns 200
curl http://portal-fe:3001/       → HTTP 200

# /healthz returns 404 (Next.js "not found" page)
curl http://portal-fe:3001/healthz → HTTP 404

Fix: Change the health probe path from /healthz to / (which returns HTTP 200).

2. 🟡 MINOR: PostgreSQL image override uses official image instead of bitnami image

values.yaml overrides the PostgreSQL image to docker.io/postgres:16, but the subchart is bitnami/postgresql which expects its own bitnami/postgresql image. The official image happens to work for basic setups because standard env vars (POSTGRES_USER, POSTGRES_PASSWORD, PGDATA) are compatible, but bitnami-specific features (scripts in /opt/bitnami/, /docker-entrypoint-initdb.d/ handling, etc.) would not work.

Fix: Remove the image override and let the bitnami chart use its default image.

Deployment Log (successful preflight)

Running preflight checks...
Loading configuration...
Portal URL: https://api7ee3-developer-portal:4321
Checking portal connection...
Portal connection successful
Connecting to database...
Database connection successful
Running migrations...
Migrations completed!
Preflight checks completed!
Starting Next.js server...
   ▲ Next.js 16.0.10
   - Local:         http://localhost:3001
   - Network:       http://0.0.0.0:3001
 ✓ Starting...
 ✓ Ready in 82ms

Will push fixes to the PR branch and re-test.

[nic-6443]

✅ Re-validation After Fixes

Fixes pushed in commit 887a7a6. Re-deployed the chart on the same kind cluster.

Results

Component	Status	Details
helm lint	✅ Pass	No errors
helm install	✅ Pass	Deployed successfully
PostgreSQL StatefulSet	✅ Running (1/1)	bitnami/postgresql image, DB ready
Portal FE Deployment	✅ Running (1/1)	Preflight passed, Next.js serving
Health probes (liveness)	✅ Pass	/ returns 200
Health probes (readiness)	✅ Pass	/ returns 200
Homepage	✅ Accessible	`<title>Home
Config status API	✅ Working	/api/config-status returns 200
Portal API connection	✅ Connected	Preflight confirmed portal connection successful
DB migrations	✅ Completed	Drizzle migrations ran successfully

Pod Status

NAME                                             READY   STATUS    RESTARTS       AGE
developer-portal-fe-postgresql-0                 1/1     Running   0              4m
portal-fe-developer-portal-fe-7f7845b88d-ff9bn   1/1     Running   6 (4m ago)     7m

Note: The 6 restarts were from the initial deployment before the bitnami PostgreSQL image was loaded into the kind cluster. Once PG was available, the FE pod started successfully and has been stable since.

Fixes Applied

1. Health probe path: Changed from /healthz (404) to / (200), made configurable via values.yaml
2. PostgreSQL image: Removed override to docker.io/postgres:16, using bitnami default image

[nic-6443]

Code Review

Bugs Fixed (pushed to branch)

I found and fixed 3 issues during deployment testing:

1. 🔴 Health probe path /healthz doesn't exist (commit 887a7a6)

   • The app has no /healthz route — returns 404, causing liveness probe failures
   • Changed to / (configurable via values.yaml)

2. 🟡 PostgreSQL image override incompatible with bitnami chart (commit 887a7a6)

   • docker.io/postgres:16 works by coincidence but is not the intended image for the bitnami subchart
   • Removed override; bitnami chart now uses its default image

3. 🔴 Secret management: portal.existingSecret breaks DB and auth secrets (commit 6d0b6c6)

   • Setting portal.existingSecret skipped creating the entire chart-managed secret
   • DB_URL and AUTH_SECRET env vars would reference a non-existent secret
   • Fixed: each existingSecret (portal, db, auth) is now evaluated independently

Convention Issues (non-blocking, for future consideration)

Compared with the existing api7 umbrella chart and gateway chart conventions:

#	Severity	Issue
1	Medium	values.yaml uses camelCase (developerPortal) while api7 chart uses snake_case (developer_portal). Consider aligning.
2	Medium	service and ingress are separate top-level keys. api7 chart nests ingress under the service key (e.g., developer_portal_service.ingress).
3	Low	Config is fragmented across portal, db, auth, app top-level keys. api7 chart uses a single developer_portal_configuration block that's dumped into the ConfigMap. The new approach gives better UX but diverges from convention.
4	Low	Image pullPolicy defaults to IfNotPresent (api7 defaults to Always). May be intentional.

What Looks Good ✅

• Template structure (_helpers.tpl, labels, selectors) follows api7 conventions well
• Independent existingSecret support (after fix) is a nice improvement
• ConfigMap env var placeholder approach (${PORTAL_TOKEN}) is clean
• Extra env vars/volumes/mounts support provides good extensibility
• Checksum annotations on deployment trigger rolling updates on config changes
• Ingress template handles multiple k8s API versions correctly