SwissHD: K3s Deployment & CI/CD

Production deployment procedures for SwissHD on Kubernetes (K3s) using ArgoCD and automated GitHub Actions continuous integration pipelines.

1. Overview

SwissHD runs as a containerized, supervised multi-process application within Kubernetes. Deployment automation follows the GitOps methodology, maintaining absolute separation between application source code and cluster infrastructure manifests across distinct repositories.

Status: Active
Target Environment: Kubernetes (K3s) / ArgoCD / GitHub Actions CI/CD
Container Architecture: Multi-stage build with Nginx Alpine and Node.js supervised by s6-overlay (v3)

2. Architecture & GitOps Pipeline

The automated deployment pipeline executes across two repositories (onthecouch/swisshd and onthecouch/k3s-repo) to build multi-architecture container images, inject runtime backend credentials, and trigger cluster rolling updates automatically upon code commits:

flowchart TD
  A["Developer Push to onthecouch/swisshd (master)"] --> B["GitHub Actions CI/CD Pipeline"]
  B --> C["1. Build Multi-Arch Image (linux/amd64 + linux/arm64)"]
  B --> D["2. Inject Secret Environment into /backend/.env"]
  C --> E["3. Push to ghcr.io/onthecouch/swisshd:SHA"]
  D --> E
  E --> F["4. Commit New Tag to k3s-repo/apps/services/swisshd.yaml"]
  F --> G["ArgoCD GitOps Controller"]
  G --> H["Detect Manifest Revision in k3s-repo"]
  H --> I["Execute Rolling Update on K3s Cluster"]
  I --> J["Dashboard Live at http://[SWISSHD_IP]:[PORT]"]

Repository	Purpose	Primary Manifests
`onthecouch/swisshd`	Application source code, frontend components, backend modules, container definitions.	`Dockerfile`, `nginx.conf`, `.github/workflows/deploy.yml`
`onthecouch/k3s-repo`	Kubernetes cluster infrastructure definitions and GitOps desired state.	`apps/services/swisshd.yaml`, ArgoCD Application definitions

3. Verification

Cluster deployment health and GitOps synchronization are validated through these procedures:

Verify container pod status indicates running execution across all supervised processes:
```
kubectl get pods -l app=swisshd
```
Inspect pod execution logs to confirm s6-overlay initialized both Nginx and Node.js without errors:
```
kubectl logs -l app=swisshd --tail=50
```
Execute a verification query against the exposed cluster endpoint to confirm HTTP 200 payload delivery:
```
curl -I https://[INTERNAL_SWISSHD_DOMAIN]/api/dashboard
```
Check the ArgoCD dashboard interface or CLI to confirm application synchronization status reads Healthy and Synced:
```
argocd app get swisshd
```

4. Troubleshooting

Symptom	Root Cause	Technical Resolution
Pod status displays `CrashLoopBackOff`	Supervisor process failure	Inspect logs via `kubectl logs`; verify `s6-overlay` script execution permissions in Dockerfile (`chmod +x /etc/services.d/*/run`).
HTTP 502 Bad Gateway on `/api/dashboard`	Backend crash or port mismatch	Confirm Node.js server is listening on port 3001; check for unhandled syntax or syntax errors in `backend/server.js`.
ArgoCD application out of sync	Image tag mismatch in `k3s-repo`	Confirm GitHub Actions CI/CD pipeline completed successfully and pushed the commit containing the new commit SHA tag.
Container pull error (`ErrImagePull`)	Registry authentication failure	Ensure K3s namespace contains a valid `imagePullSecret` for `ghcr.io` or that the repository image package is marked public.

5. Cluster Integration

SwissHD reads telemetry from the Kubernetes API and configured monitoring and application services. NetworkPolicy rules must allow only the declared service selectors and ports required by the dashboard. The application image is built by CI, referenced by an immutable commit identifier, and reconciled by ArgoCD.

Use the internal HTTPS route for browser access. Keep private addresses, bearer tokens, and deployment credentials outside public documentation.