🚀 Slava's Home Server Automation (Ansible Project)

Welcome to the magic folder that controls all the servers! 🎩✨

If you've ever played a video game where you build a city, this is kind of like the control panel for our real-life digital city. Instead of logging into every single computer (server) to install things one by one, we use a tool called Ansible to give them instructions all at once.

Our digital house is now more modern, secure, and autonomous than ever.

---

📖 Table of Contents

1. What is this? (The Simple Explanation)
2. How the Folders are Organized
3. The Core Services We Run
4. 🛡️ Security Hardening & Monitoring
5. ⚙️ Automated Maintenance
6. How to Manage the Servers
7. 🔐 SSO Integration Tutorial (Authelia + PVE)
8. 📚 Specialized Manuals & Guides

---

1. What is this? (The Simple Explanation)

Imagine you have 20 robots, and you want them all to put on a blue hat.

• The hard way: Walk up to each robot, hand it a hat, and tell it to put it on.
• The Ansible way: You stand at a microphone, shout "Everyone put on a blue hat!" and they all do it at the exact same time.

Ansible is our microphone.

• The Playbooks are the scripts we read into the microphone (e.g., "Install Docker!").
• The Inventory is our list of robots (IP addresses) so the microphone knows who to talk to.

---

2. How the Folders are Organized

Here is what all the folders in this project actually do:

• 📂 inventory/: This is the address book.
  • hosts.yml: A list of every single server we own and what "groups" they belong to.
  • group_vars/: Settings that apply to a whole group. all.yml contains fleet-wide settings like centralized SSH keys and proxy info.
  • host_vars/: Settings for one specific server (like unique firewall ports).
• 📂 playbooks/: These are the instruction manuals.
• 📂 roles/: These are reusable "recipes" (e.g., how to install Caddy or CrowdSec).
• 📂 keys/: Contains our digital keys (SSH keys) for passwordless login.

---

3. The Core Services We Run

Our home network runs a suite of high-performance services, all accessible via local DNS:

• 🏠 Homepage (home.slavko.kyiv.ua): Our unified service portal. A single dashboard to access everything from Media to Security.
• 🌐 Caddy: The Traffic Cop. Handles HTTPS certificates and reverse proxies all traffic to the correct container.
• 🔐 Authelia SSO: The Bouncer. Provides Single Sign-On via OIDC for Proxmox, NAS, and Backup servers.
• 🛑 Pi-hole: The Ad Blocker and Phonebook. Handles all local .slavko.kyiv.ua DNS resolution internally.
• 🔍 SearXNG: The Private Eye. Our own private, ad-free metasearch engine.
• 📊 Zabbix: The Doctor. Constant health monitoring with custom templates for Docker and Security.
• 💾 Immich & Jellyfin: Our personal Media and Photo clouds.
• 📦 APT Cacher & Docker Registry: The Warehouse. Local caching of all software updates and container images.
• ☁️ Rclone & Restic: The Vault. Automated local (NAS) and offsite (Google Drive) encrypted backups.

---

4. 🛡️ Security Hardening & Monitoring

Our infrastructure is hardened to a Lynis 80+ score using aggressive industry standards.

Key Hardening Features:

• Deep Kernel Protection: Aggressive sysctl hardening (disabling unprivileged BPF, restricting ptrace/kexec) and blacklisting 20+ dangerous kernel modules.
• Intrusion Prevention (CrowdSec): A fleet-wide CrowdSec mesh has replaced Fail2Ban, providing community-driven threat intelligence and banning bad actors at the UFW level.
• Docker Security: Globally enforced no-new-privileges and restricted Inter-Container Communication (ICC).
• Infrastructure Isolation: PVE Native Firewall protects the main physical nodes, allowing management access only from trusted subnets.
• Automated UFW Firewall: A flexible ufw role is gradually deployed to managed servers (Caddy, Vaultwarden, etc.), strictly whitelisting only the necessary ports and denying all other incoming traffic.
• SSH Security: Password login is disabled. Access is controlled via a centralized public key list in group_vars/all.yml.

---

5. ⚙️ Automated Maintenance

We treat our servers like a self-healing fleet. Most maintenance is now automated:

• kernel_cleanup.yml: Automatically purges old Linux kernels and leftover 'rc' configuration files to keep the boot partition clean.
• monitor_security.yml: Runs every 4 hours to check for upgradable packages and reboot-required flags, sending Priority 9 Gotify alerts for urgent items.
• vulnerability_fix.yml: A "fast-response" playbook for rolling out urgent security patches fleet-wide without a full system run.
• docker_maintenance.yml: Weekly pruning of unused images, containers, and volumes to reclaim disk space.
• gdrive_backup.yml & restic_backup.yml: Automated 3-2-1 backup pipeline. Restic backs up to the local NAS nightly, and Rclone safely mirrors those encrypted backups to Google Drive.

---

6. How to Manage the Servers

Precision Operations

We use Tags and Limits to manage the fleet efficiently:

• Apply ONLY Security Hardening:

  ansible-playbook playbooks/site.yml --tags hardening
  

• Update a Specific Host (e.g., SearXNG):

  ansible-playbook playbooks/site.yml --limit searxng
  

• Run Vulnerability Scan:

  ansible-playbook playbooks/vulnerability_scan.yml
  

---

7. 🔐 SSO Integration Tutorial (Authelia + PVE)

We use Authelia as an OpenID Connect (OIDC) provider to secure our Proxmox infrastructure.

How it works:

1. Authelia Side: Configured in roles/authelia/templates/configuration.yml.j2 under identity_providers: oidc. It defines clients for proxmox, nas, and backup.
2. Proxmox Side:
   • Go to Datacenter > Permissions > Realms.
   • Add OpenID Connect Server.
   • Issuer URL: https://auth.slavko.kyiv.ua
   • Client ID: proxmox
   • Username Claim: preferred_username
3. Permissions: Users created via SSO must be granted permissions in PVE (e.g., pveum user permissions slava@oidc).

This setup allows "One-Factor" login to all infrastructure nodes once you've authenticated with Authelia.

---

8. 📚 Specialized Manuals & Guides

For detailed instructions, refer to these dedicated manuals:

• ⚡ Ansible Cheat Sheet - Quick reference for common commands and targeting.
• 💾 Backup & Recovery Manual - Restic and Proxmox backup strategies.
• 🛡️ Fleet Hardening Manual - Deep dive into our Lynis-based security.
• 🏗️ Forgejo CI/CD - How we automate playbooks via GitOps.
• 🔋 Power Optimization Guide - N100 efficiency and powertop settings.
• 🔐 Credentials & Secrets - Ansible Vault usage and password management.
• 🪄 A Beginner's Guide - Conceptual overview for non-technical users.