Self-Hosted Infrastructure Framework

Infrastructure-as-code framework for managing multi-server Docker-based services with automated deployment, monitoring, and backups.

Quick Start

# Install Deno
curl -fsSL https://deno.land/install.sh | sh

# Install Ansible
# For Debian/Ubuntu
sudo apt update && sudo apt install -y ansible
# For Fedora/CentOS
sudo dnf install -y ansible

# Clone and setup
git clone https://github.com/spy4x/homelab.git ~/homelab && cd ~/homelab
cp servers/home/.env.example servers/home/.env  # Copy example env

# Edit servers/home/.env with your ssh params, domain, email, etc.
nano servers/home/.env # if using nano
# OR 
code servers/home/.env  # if using VSCode

# Configure server with Ansible - Install
deno task ansible ./ansible/playbooks/initial-setup/base.yml home 

# Deploy to server
deno task deploy home

Documentation

• Get Started - Initial setup & deployment
• Architecture - System design & data flow
• Adding Services - Service integration guide
• Troubleshooting - Debug common issues
• Backup System - Restic-based backup details

Example Servers

This repo includes three real servers as reference implementations:

• home - Primary services (media, automation, productivity)
• cloud - Email & external monitoring (Hetzner VPS)
• offsite - Backup replication (Raspberry Pi)

Repository Structure

stacks/{name}/          # ALL service stacks (catalog)
  └── {service}/        # Traefik, Immich, etc.
      ├── compose.yml
      ├── backup.ts
      └── README.md
servers/{name}/         # Server-specific config
  ├── config.json       # Which stacks to deploy
  ├── .env             # Environment variables
  └── configs/         # Server-specific overrides
      └── backup/      # Non-service backups only
scripts/                # Management tools (Deno)
  ├── deploy/          # Deployment automation
  ├── backup/          # Backup system
  └── ansible/         # Ansible wrapper
ansible/                # Server provisioning
docs/                   # Framework documentation

Available Services

Infrastructure:

• Traefik - Reverse proxy with automatic SSL
• Watchtower - Automatic container updates
• Gatus - Health monitoring and status page
• WireGuard - VPN server

Communication & Notifications:

• ntfy - Push notifications
• Mailserver - Self-hosted email server
• Roundcube - Webmail client

Media & Entertainment:

• Immich - Photo and video management
• Jellyfin - Media server
• Audiobookshelf - Audiobook & podcast server
• Piped - YouTube alternative frontend
• MeTube - YouTube downloader
• Transmission - Torrent client

Productivity & Tools:

• Vaultwarden - Password manager (Bitwarden)
• Open WebUI - AI chat interface
• FreshRSS - RSS feed reader
• FileBrowser - Web-based file manager
• Radicale - CalDAV/CardDAV server
• Syncthing - File synchronization

Home Automation:

• Home Assistant - Home automation platform
• AdGuard - Network-wide ad blocking

Development:

• Woodpecker - CI/CD server
• Healthchecks - Cron monitoring

Web Server:

• Nginx - Web server and reverse proxy

Core Features

Deployment - Automated rsync + Docker Compose deployment via deno task deploy
Backups - Restic-based with per-service configs, see backup README
Monitoring - Cross-server health checks (Gatus) + notifications (ntfy)
Provisioning - Ansible playbooks for server hardening & maintenance
Service Discovery - Traefik reverse proxy with automatic SSL

Common Tasks

# Deploy server config
deno task deploy <server>

# SSH to server
deno task ssh <server>

# Run Ansible playbook
deno task ansible <playbook> <server>

# Manual backup
cd servers/<server> && deno run --env-file=.env -A ../../scripts/backup/+main.ts

See server docs for server-specific notes and service docs for available services.