Skip to content

Swiss-HD: Deployment & Configuration

Implementation procedures for the Swiss-HD dashboard within a Node.js-based environment.

1. Overview

Swiss-HD is deployed as a modern Vite-based React application. It requires a reverse proxy or service mesh for optimal performance and secure integration with internal APIs (e.g., Proxmox VE, K3s, Grafana, n8n).

2. Requirements & Prerequisites

Necessary components or states prior to implementation:

  • Node.js: Version 18.0.0 or higher.
  • Package Manager: npm or yarn.
  • API Access: Valid tokens for integrated services (see Environment Variables below).
  • Network Connectivity: Unhindered access to internal service endpoints.

3. Implementation Procedure

A. Environment Configuration

  1. Initialize the repository and install essential dependencies: 

    npm install

  2. Create an environment configuration file named .env.local in the project root.

  3. Define the required integration parameters (see Environment Variables section below).

B. Service Deployment

  1. Execute the development server for initial validation: 

    npm run dev

  2. Generate the optimized production bundle: 

    npm run build

  3. Deploy the resulting assets in the dist/ directory to a static web server or containerized Nginx instance.

4. Environment Variables

Proxmox Integration

VITE_METRIC_1_TYPE=proxmox
VITE_METRIC_1_API_URL=/api/proxmox/api2/json/nodes/[NODE_NAME]/status
VITE_METRIC_1_AUTH="PVEAPIToken=[USER]@[REALM]![TOKEN_ID]=[SECRET]"

K3s Integration

VITE_K3S_AUTH="Bearer YOUR_TOKEN"

Create the ServiceAccount and token: 

kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: dashboard
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: dashboard-metrics
rules:
  - apiGroups: ["metrics.k8s.io"]
    resources: ["nodes"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["nodes", "pods"]
    verbs: ["get", "list"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: dashboard-metrics
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: dashboard-metrics
subjects:
  - kind: ServiceAccount
    name: dashboard
    namespace: default
EOF

kubectl create token dashboard --duration=8760h

Google Calendar Integration

VITE_GOOGLE_CALENDAR_ID="yourname@gmail.com"
VITE_GOOGLE_CALENDAR_API_KEY=your_api_key

Arr Stack (Sonarr, Radarr, Lidarr)

VITE_SONARR_API_KEY=your_sonarr_key
VITE_RADARR_API_KEY=your_radarr_key
VITE_LIDARR_API_KEY=your_lidarr_key

qBittorrent

VITE_QBITTORRENT_USERNAME=admin
VITE_QBITTORRENT_PASSWORD=yourpassword

Jellyfin

VITE_JELLYFIN_API_KEY=your_jellyfin_key

ArgoCD

VITE_ARGOCD_TOKEN=your_argocd_token

Grafana

VITE_GRAFANA_API_KEY=glsa_xxxxxxxx

Setup: Administration → Service Accounts → Create Service Account → Add Viewer role → Create token

n8n

VITE_N8N_API_KEY=n8n_api_xxxxxxxx

Setup: Settings → n8n API → Create API Key

5. Configuration Standards

  • Proxy Layer: Vite's internal proxy is utilized during development to bypass CORS limitations when communicating with internal APIs. In production (K3s), Nginx handles the proxy — see K3s Deployment.
  • Security: API credentials must remain restricted to .env.local for local development. For production, credentials are stored as GitHub Secrets and baked into the Docker image at build time.
  • Persistence: Component state is managed via React hooks; no external database is required for core functionality.

6. Production Deployment (K3s + ArgoCD)

For production deployment on K3s via ArgoCD with GitHub Actions CI/CD, see the dedicated guide:

→ K3s Deployment & CI/CD

This covers: - Dockerfile and multi-arch build (amd64 + arm64) - Nginx proxy configuration replacing the Vite dev proxy - GitHub Actions workflow (build → push to ghcr.io → update k3s-repo) - ArgoCD GitOps setup - Adding new services with secrets - Troubleshooting common deployment errors

6. Verification

System health is validated through these procedures:

  1. Confirm successful compilation without TypeScript errors.
  2. Verify visual rendering of the grid-based interface at localhost:3000.
  3. Validate telemetry data by checking the "Metrics" panel for active updates.
  4. Inspect the browser console to ensure no 401 (Unauthorized) or 403 (Forbidden) errors originate from API endpoints.
  5. Verify service cards display expected metrics (e.g., dashboards: 15 | alerts: 3 for Grafana).

7. Troubleshooting

Issue Solution
401 Unauthorized Verify API tokens are correct and not expired
Metrics not displaying Check appType is set correctly in config.yaml
CORS errors Ensure Vite proxy is configured correctly
Pod count shows 0/0 Verify K3s token has proper RBAC permissions