Architecture

The platform follows a cloud-native architecture with GitOps at its core.

System Overview

CI/CD Pipeline

GitOps Flow

Cost Breakdown

Monthly infrastructure costs for the homelab platform.

Cost Optimization Tips

• Use fewer/smaller nodes during low-usage periods
• Enable DO's auto-scaling for dynamic workloads
• Monitor actual storage usage — reduce PVC sizes if over-provisioned
• Consider spot instances for non-critical workloads
• Consolidate services that don't need separate deployments

Cluster Setup

How the DOKS cluster is provisioned and configured.

Cluster Creation

# Create cluster with 2 node pools
doctl kubernetes cluster create homelab \
  --region sgp1 \
  --version latest \
  --node-pool "name=basic-pool;size=s-2vcpu-4gb;count=3" \
  --node-pool "name=storage-pool;size=s-4vcpu-8gb;count=2" \
  --auto-upgrade --wait

# Save kubeconfig
doctl kubernetes cluster kubeconfig save homelab

# Verify
kubectl get nodes

Node Topology

Node Assignments

Infrastructure Components

Core infrastructure that powers the entire platform.

NGINX Ingress Controller

Routes external traffic to internal services based on hostname. Installed via Helm.

• Creates a DigitalOcean Load Balancer automatically
• Handles TLS termination with Let's Encrypt certificates
• Routes traffic based on host headers (e.g., gitea.akze.net)

Cert-Manager + Let's Encrypt

Automatically provisions and renews SSL certificates for all services.

DigitalOcean Block Storage

SSD-backed persistent volumes for stateful services. Automatically provisioned by the DO CSI driver.

DNS Configuration

All services are accessed via subdomains of akze.net, managed through Cloudflare.

DNS Records

All Services

Every service running on the platform, organized by category.

DevOps Tools

Professional DevOps tools for development and operations workflows.

ArgoCD — GitOps Engine

Continuously monitors the Gitea repository and automatically applies any manifest changes to the Kubernetes cluster. Supports auto-sync, self-healing, and rollback.

Gitea — Source Control

Lightweight, self-hosted Git server. Stores all Kubernetes manifests, Helm values, and deployment configurations. Acts as the single source of truth for the entire infrastructure.

Grafana — Observability

Dashboard platform for visualizing metrics. Connects to Prometheus data sources to display cluster resource usage, service health, and custom business metrics.

Uptime Kuma — Monitoring

Beautiful status page and uptime monitor. Checks all services periodically and sends alerts when services go down.

Homelab Applications

Personal productivity and entertainment applications.

Nextcloud

Complete self-hosted productivity suite with file sync, calendar, contacts, and collaborative editing. Uses Apache backend with 50Gi persistent storage.

Jellyfin

Free software media system. Streams movies, music, and TV shows to any device. Optimized with separate config and cache volumes (30Gi total).

Vaultwarden

Lightweight Bitwarden-compatible password manager. Stores all passwords encrypted, supports 2FA, and syncs across all devices.

Pi-hole

Network-level ad and tracker blocking. Works as a DNS sinkhole, blocking ads for all devices on the network without installing browser extensions.

Home Assistant

Open-source home automation platform. Connects to smart home devices, creates automations, and provides a unified dashboard for all IoT devices.

GitOps Workflow

Infrastructure as Code with automatic synchronization.

Repository Structure

homelab/
├── infrastructure/          # Core infrastructure
│   ├── nginx-ingress/       #   NGINX Ingress Controller
│   ├── cert-manager/        #   SSL certificates
│   └── storage/             #   Block storage config
├── apps/                    # Applications
│   ├── devops/              #   DevOps services
│   │   ├── argocd/          #     ArgoCD configuration
│   │   ├── gitea/           #     Gitea deployment
│   │   ├── grafana/         #     Grafana deployment
│   │   └── uptime-kuma/     #     Uptime monitoring
│   └── homelab/             #   Homelab services
│       ├── jellyfin/        #     Media streaming
│       ├── nextcloud/       #     File sync
│       ├── vaultwarden/     #     Password manager
│       ├── pihole/          #     Ad blocker
│       └── home-assistant/  #     Smart home
└── scripts/                 # Deployment scripts
    ├── 01-infrastructure.ps1
    ├── 02-devops.ps1
    └── 03-homelab.ps1

Principles

• Declarative: Everything defined in YAML manifests
• Versioned: All changes tracked in Git history
• Automatic: No manual kubectl apply needed
• Self-Healing: ArgoCD auto-corrects drift
• Auditable: Every change has a commit message and author

CI/CD Pipeline

Automated build, test, and deployment pipeline for application code.

GitHub Actions Workflow

name: CI/CD Pipeline
on:
  push:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
      - run: go test -v ./...          # Run tests
      - uses: docker/login-action@v3   # Login to GHCR
      - uses: docker/build-push-action@v5  # Build & push

  cd:
    needs: ci
    runs-on: ubuntu-latest
    steps:
      - run: |
          git clone https://gitea.akze.net/user/homelab.git
          # Update image tag in manifest
          sed -i "s|image: .*|image: ghcr.io/user/app:${SHA}|" ...
          git push  # Push to Gitea

Why GHCR Over DO Registry?

Security Architecture

How the platform handles authentication, secrets, and access control.

Secret Management

Security Principles

Network Security

Troubleshooting

Common issues and their solutions.

Service Returns 404

spec:
  ingressClassName: nginx  # Must be present
  tls: ...

ArgoCD Redirect Loop

# Fix: Set insecure mode
kubectl patch configmap argocd-cmd-params-cm -n argocd \
  --type merge -p '{"data":{"server.insecure":"true"}}'
kubectl rollout restart deployment/argocd-server -n argocd

ImagePullBackOff

# Create pull secret
kubectl create secret docker-registry ghcr-pull-secret \
  -n <namespace> \
  --docker-server=ghcr.io \
  --docker-username=<github-user> \
  --docker-password=ghp_YOUR_TOKEN

# Reference in deployment
# spec.template.spec.imagePullSecrets: [{name: ghcr-pull-secret}]

SSL Certificates Pending

kubectl get certificates -A
kubectl describe certificate <name> -n <namespace>
kubectl logs deploy/cert-manager -n cert-manager

Common kubectl Commands

# Check all pods
kubectl get pods --all-namespaces

# Describe a failing pod
kubectl describe pod <name> -n <namespace>

# View logs
kubectl logs <pod> -n <namespace> --tail=50

# Restart a deployment
kubectl rollout restart deployment/<name> -n <namespace>

# Check ArgoCD applications
kubectl get applications -n argocd

# Force ArgoCD refresh
kubectl patch application <name> -n argocd \
  --type merge -p '{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"hard"}}}'