HomeLab Infrastructure

Projects | | Links: Website | Wiki

HomeLab Infrastructure

유휴 노트북 한 대로 시작한 홈서버를, 베어메탈 미니PC + Proxmox + 멀티노드 Kubernetes + ArgoCD GitOps 파이프라인으로 발전시킨 인프라입니다.
프로젝트 기여도 100%

1. Overview

유휴 노트북 한 대로 Nginx + Self-hosted Runner 기반 CI/CD 서버를 구축한 것을 시작으로, 이후 미니PC(Ryzen 7 4700U, 16GB RAM)에 Proxmox VE 하이퍼바이저를 설치하고 멀티 노드 Kubernetes 클러스터로 발전시켰습니다.

현재는 GitHub Actions(CI) + ArgoCD(CD) + Kustomize 기반 GitOps 파이프라인으로, 코드 푸시만으로 도커 이미지 빌드부터 프로덕션 배포까지 완전 자동화되어 있습니다.

2. Phase 1 — 유휴 노트북 CI/CD Server

Home-Server Architecture

Home Server Architecture

Home-Server CICD Architecture

Architecture of the self-hosted CI/CD pipeline

  • GitHub Actions Self-hosted Runner를 이용해 60초 안에 빌드-배포가 완료되는 CI/CD 파이프라인 구축
  • Nginx로 정적 사이트 호스팅, rsync --delete로 변경 파일만 동기화
  • TLS(Let’s Encrypt A+), iptables 기본 DROP, Fail2Ban(주 500건 차단), Google OTP 2FA

3. Phase 2 — Proxmox K8s GitOps Platform

Architecture


HomeServer

User → Public IP (DDNS: kpryu.sytes.net)
     → LG U+ Router (Port Forwarding 80/443)
     → MetalLB VIP (192.168.219.240)
     → Nginx Ingress Controller
     → Services (Blog: /, Wiki: /wiki)

Infrastructure Layer

구성요소기술
HypervisorProxmox VE 9.x
K8sMulti-node cluster (1 Master + 2 Worker)
Load BalancerMetalLB (L2 mode)
IngressNginx Ingress Controller
TLScert-manager + Let’s Encrypt (자동 갱신)
DNSNo-IP DDNS + Pi-hole (Split-Horizon)
VPNTailscale (원격 관리)

CI/CD Pipeline (GitOps)

단계도구
SourceGitHub Monorepo (paths 필터로 독립 빌드)
BuildGitHub Actions Self-hosted Runner (AMD64 VM)
RegistryDocker Hub
ManifestKustomize (별도 매니페스트 레포)
DeployArgoCD (Pull-based Sync)

Hosted Applications

서비스프레임워크경로
Main BlogJekyll (Hydejack)/
DevOps WikiDocusaurus/wiki
Control CenterHomepage (gethomepage)내부망 전용

4. Key Troubleshooting

#이슈원인해결
1Exit 139 (Segfault)Alpine musl libc vs Ruby C 확장 충돌Debian-slim 멀티 스테이지 빌드로 전환
2cert-manager 무한 PendingNAT Loopback — 공유기가 내부→공인IP→내부 차단CoreDNS에 Split-Horizon DNS 적용
3exec format errorMac(ARM64)에서 빌드 → 서버(AMD64) 불일치Self-hosted Runner VM에서 네이티브 빌드
4Nginx 403 on sub-pathIngress /wiki 경로와 컨테이너 내부 경로 불일치Docker COPY 목적지를 /html/wiki로 조정
5ArgoCD repo-server Unknown네트워크 순단으로 파드 좀비 상태--force --grace-period=0 강제 삭제 후 재동기화
6Dynamic IP TimeoutISP IP 변경 + DDNS 갱신 누락No-IP 즉시 수동 갱신, 자동화 CronJob 도입 예정

5. Security

영역적용 내용
TLScert-manager + Let’s Encrypt (자동 갱신, HTTPS 강제)
방화벽iptables 기본 DROP 정책, K8s 서비스 포트만 허용
SSH단일 사용자 + Google OTP 2FA + Fail2Ban
네트워크 분리Public 서비스: Ingress 외부 개방 / Private: NodePort 내부망 전용
원격 접근Tailscale VPN (SSH 터널링 경유)

6. Key Results

지표Phase 1Phase 2
배포 시간60초 (rsync)~3분 (GitOps 자동)
인프라노트북 1대, NginxProxmox + K8s 3노드
서비스블로그 1개블로그 + 위키 + 대시보드
가용성nginx reload (0초)Ingress 100+ days uptime
비용0원0원 (자가 호스팅)
SSLCertbot A+cert-manager 자동 갱신

7. Used Skills

  • Proxmox VE
  • Kubernetes (K3s → kubeadm)
  • MetalLB, Nginx Ingress Controller
  • cert-manager, Let’s Encrypt
  • GitHub Actions (Self-hosted Runner)
  • ArgoCD, Kustomize
  • Docker (Multi-stage Build)
  • Jekyll, Docusaurus, Nginx
  • Pi-hole (DNS), Tailscale (VPN)
  • iptables, Fail2Ban, Google OTP
  • DDNS (No-IP)
  • Prometheus, Grafana