Skip to content

Infrastructure Overview

This document provides a high-level overview of the dehott.link homelab infrastructure. The environment is built on a single physical node running Ubuntu 22.04 LTS (via WSL2 on Windows 11), utilizing Docker Compose for container orchestration and Traefik for reverse proxying and SSL termination.

Core Architecture

The homelab follows a containerized microservices architecture. All services are deployed as Docker containers, defined in declarative docker-compose.yml files. This approach ensures reproducibility, easy updates, and clean separation of concerns.

Hardware Node (BLD)

  • OS: Windows 11 Pro with Ubuntu 22.04 LTS (WSL2)
  • Role: Primary compute and storage node
  • Network: Connected to the local LAN, accessible remotely via Tailscale

Network & Routing

  • Reverse Proxy: Traefik handles all incoming HTTP/HTTPS traffic, routing requests to the appropriate containers based on domain names (e.g., sonarr.dehott.link).
  • SSL/TLS: Traefik automatically provisions and renews Let's Encrypt certificates using the DNS-01 challenge via the Cloudflare API.
  • DNS Management: Cloudflare manages the dehott.link domain. A dedicated cloudflare-ddns container automatically updates DNS records when the public IP changes.
  • Docker Networks: Services are isolated into logical Docker networks (e.g., homelab-personal, homelab-infrastructure) to control inter-container communication.

Directory Structure

The entire homelab configuration and persistent data are stored in a structured directory on the host machine, typically at /home/tim/homelab/.

/home/tim/homelab/
├── .env                    # Global environment variables and secrets
├── docker-compose/         # Docker Compose definitions
│   ├── infrastructure/     # Core services (Traefik, DDNS, MkDocs)
│   ├── personal/           # Personal services (Nextcloud, Media Stack)
│   └── ai/                 # AI services (Ollama, Open WebUI)
└── data/                   # Persistent container data (volumes)
    ├── traefik/
    ├── sonarr/
    ├── searxng/
    └── ...

Security Posture

  • External Access: Only ports 80 and 443 are forwarded from the router to the Traefik container. No individual service ports are exposed directly to the internet.
  • VPN: Tailscale provides secure, zero-trust remote access to the host machine and internal services without requiring additional port forwarding.
  • Authentication: Services exposed to the internet either have built-in authentication (e.g., Nextcloud, Gitea) or are protected by middleware.

Deployment Workflow

Deploying a new service involves three standard steps:

  1. Create Configuration: Define the service in a new or existing docker-compose.yml file, ensuring it connects to the correct Traefik network and includes the necessary routing labels.
  2. Update DNS: Add the new subdomain to the DOMAINS list in the cloudflare-ddns configuration.
  3. Deploy: Run docker compose up -d to pull the image and start the container. Traefik automatically detects the new service and provisions an SSL certificate.