Skip to content

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:

  1. Verify container pod status indicates running execution across all supervised processes: 
    kubectl get pods -n services -l app=swisshd
  2. Inspect pod execution logs to confirm s6-overlay initialized both Nginx and Node.js without errors: 
    kubectl logs -n services -l app=swisshd --tail=50
  3. Execute a verification query against the exposed cluster endpoint to confirm HTTP 200 payload delivery: 
    curl -I http://[SWISSHD_IP]:[PORT]/api/dashboard
  4. 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.