homepage

docs/REFERENCE.md

@@ -725,6 +725,59 @@ TLS terminates at Traefik; ArgoCD runs in insecure mode behind the proxy.
 
 ## Infrastructure Components
 
+### Homepage (Platform Dashboard)
+
+**Chart**: `jameswynn/homepage`
+**Namespace**: `homepage`
+**URL**: `https://start.forteapps.net`
+
+Platform dashboard that auto-discovers deployed apps via Kubernetes service annotations.
+
+**Discovery mechanism**: Services annotated with `gethomepage.dev/enabled: "true"` appear in the dashboard. Apps not deployed = annotations absent = not shown. Fully dynamic per environment.
+
+**Annotated services**:
+| Service | Namespace | Group | Widget |
+|---------|-----------|-------|--------|
+| `gitea-http` | `gitea` | DevOps | `gitea` |
+| `argocd-server` | `argocd` | DevOps | `argocd` |
+| `keycloak` | `keycloak` | Identity | none |
+| `grafana` | `monitoring` | Monitoring | `grafana` |
+| `karpor-server` | `karpor` | DevOps | none |
+
+**Adding a new app**: Annotate the app's Service in its Helm values:
+```yaml
+service:
+  annotations:
+    gethomepage.dev/enabled: "true"
+    gethomepage.dev/name: "My App"
+    gethomepage.dev/description: "What it does"
+    gethomepage.dev/group: "GroupName"
+    gethomepage.dev/icon: "icon-name"     # https://github.com/walkxcode/dashboard-icons
+    gethomepage.dev/href: "https://myapp.forteapps.net"
+    # Optional live widget:
+    gethomepage.dev/widget.type: "myapp"
+    gethomepage.dev/widget.url: "https://myapp.forteapps.net"
+    # gethomepage.dev/widget.key: "{{HOMEPAGE_VAR_MYAPP_TOKEN}}"
+```
+
+**Widget API credentials**: Inject via env vars into the Homepage pod:
+```yaml
+# In homepage-values.yaml per environment
+env:
+- name: HOMEPAGE_VAR_GRAFANA_TOKEN
+  valueFrom:
+    secretKeyRef:
+      name: homepage-widget-credentials
+      key: grafana-token
+```
+Then reference as `gethomepage.dev/widget.key: "{{HOMEPAGE_VAR_GRAFANA_TOKEN}}"`.
+
+**Values files**:
+- `infra/values/base/homepage-values.yaml` — RBAC, kubernetes mode, layout
+- `infra/values/{env}/homepage-values.yaml` — hostname per environment
+
+---
+
 ### Traefik
 
 **Chart**: `traefik/traefik`