🏠 Homelab Infrastructure

Self-hosted infrastructure running on Podman with Systemd Quadlet integration.

Dashboard: home.simonemiglio.eu

📌 Primary Repository: Forgejo
🪞 Mirrors: GitHub • GitLab • Codeberg

---

📋 Table of Contents

• Services
• Quick Start
• Architecture
• Project Structure
• Management
• Troubleshooting

---

🌐 Services

Service	Domain	Description
Homepage	home.simonemiglio.eu	Dashboard
Portfolio	simonemiglio.eu	Personal website
Immich	gallery.simonemiglio.eu	Photo management
Firefly III	finanza.simonemiglio.eu	Finance tracker
Firefly Importer	importer.finanza.simonemiglio.eu	Bank data import
Metabase	analytics.simonemiglio.eu	Financial analytics
Actual Budget	(internal)	Budget tracking
FastFood	fastfood.simonemiglio.eu	Demo app
Uptime Kuma	status.simonemiglio.eu	Monitoring
IT-Tools	tools.simonemiglio.eu	Developer utilities
Portainer	portainer.simonemiglio.eu	Container UI
Cockpit	panel.simonemiglio.eu	System admin
Garage S3	s3.simonemiglio.eu	S3-compatible storage
Garage WebUI	garage.simonemiglio.eu	S3 admin interface

---

🚀 Quick Start

Full setup guide: See SETUP.md for complete instructions.

Prerequisites

• Ubuntu 24.04 LTS (or similar)
• 2+ vCPU, 4+ GB RAM
• Domain with DNS access

Step 1: Clone Repositories

This setup uses 3 independent repositories:

cd ~

# Infrastructure (required)
git clone https://forgejo.it/simonemiglio/Homelab.git podman
cd podman

# Portfolio source (if needed)
git clone https://forgejo.it/simonemiglio/Website.git site_sources

# FastFood source (if needed)
git clone https://forgejo.it/simonemiglio/FastFood.git FastFood

Step 2: Create Secrets

./scripts/create_secrets.sh

Step 3: Configure

cp config_examples/Caddyfile.example data/caddy/Caddyfile
# Edit with your domain

Step 4: Start Services

./manage_finale.sh
# Select option 1, then 'a' for all

---

🏗️ Architecture

Internet (HTTPS)
       │
       ▼
┌─────────────────────────────────────────────┐
│  Caddy (Port 80/443)                        │
│  Reverse Proxy + Auto HTTPS                 │
└─────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────┐
│  services_net (Podman Network)              │
│                                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │Homepage │ │ Immich  │ │Firefly  │       │
│  │   Pod   │ │   Pod   │ │   Pod   │       │
│  └─────────┘ └─────────┘ └─────────┘       │
│                                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │Metabase │ │FastFood │ │ Uptime  │       │
│  │   Pod   │ │   Pod   │ │  Kuma   │       │
│  └─────────┘ └─────────┘ └─────────┘       │
│                                             │
│  ┌─────────┐ ┌─────────┐                   │
│  │IT-Tools │ │ Garage  │                   │
│  │   Pod   │ │   Pod   │                   │
│  └─────────┘ └─────────┘                   │
└─────────────────────────────────────────────┘

Key Concepts

Component	Purpose
Rootless Podman	Containers run as user, not root
Quadlets	Systemd integration for auto-start
Caddy	Automatic HTTPS with Let's Encrypt
services_net	Internal DNS between pods

---

📁 Project Structure

podman/
├── kube_yaml/               # Pod definitions
│   ├── caddy.pod.yaml
│   ├── homepage.pod.yaml
│   ├── site.pod.yaml        # Portfolio website
│   ├── immich.pod.yaml
│   ├── firefly.pod.yaml
│   ├── firefly-importer.pod.yaml  # Bank data importer
│   ├── metabase.pod.yaml    # Financial analytics dashboard
│   ├── actual.pod.yaml      # Actual Budget
│   ├── fastfood.pod.yaml
│   ├── uptime-kuma.pod.yaml
│   ├── portainer.pod.yaml
│   ├── garage.pod.yaml      # Gitignored (contains auth hash)
│   └── it-tools.pod.yaml
│
├── config_examples/         # Configuration templates
│   ├── Caddyfile.example
│   ├── garage.pod.yaml.example
│   └── services.yaml.example
│
├── scripts/                 # Utility scripts
│   ├── create_secrets.sh    # Interactive Podman secrets setup
│   ├── nightly_backup.sh    # Automated nightly backups (cron)
│   ├── restore_wizard.sh    # Interactive backup restore from S3
│   ├── setup_permission_fix.sh  # Fix volume permissions after reboot
│   ├── setup_fail2ban.sh    # SSH brute-force protection
│   └── setup_cockpit.sh     # Install Cockpit web UI
│
├── logs/                    # Backup logs (auto-created)
│
├── docs/                    # Additional documentation
│   ├── ARCHITETTURA.md      # Architecture (Italian)
│   └── metabase_queries.md  # SQL queries for Metabase dashboards
│
├── manage_finale.sh         # Main management script
├── README.md                # This file
└── SETUP.md                 # Full setup guide

Related Repositories

Repository	Content
Website	Portfolio source code
FastFood	FastFood app source

---

🔧 Management

Interactive Menu

./manage_finale.sh

Options:

1. Start/Restart Services
2. Update Services (with Pull & Backup)
3. Stop Services
4. Backup Immich (DB dump → cloud sync)
5. Backup Firefly (DB + data → cloud sync)
6. Backup Metabase (H2 DB → cloud sync)
7. Backup System Tools (Kuma/Portainer)
8. List Backups
9. Restore / Download from S3
10. Full System Cleanup
11. Setup & Verify Quadlet Config
12. Restart Caddy Proxy
13. Optimize Databases

Automated Backups

Nightly backups run automatically at 3:00 AM via cron:

# Check nightly backup logs
cat ~/podman/logs/nightly_backup_$(date +%Y-%m-%d).log

# View cron jobs
crontab -l

Direct Commands

# Check all pods
podman pod ps

# Check all containers
podman ps

# Restart a service
systemctl --user restart immich.service

# View logs
journalctl --user -u caddy.service -f

Common Tasks

Task	Command
Restart Caddy	systemctl --user restart caddy.service
Check status	podman pod ps
View logs	podman logs <container-name>
Clean up	podman system prune -a

---

🔒 Security

Feature	Implementation
HTTPS	Caddy + Let's Encrypt (auto)
Rootless	All containers run as user
Fail2Ban	SSH brute-force protection
Headers	HSTS, CSP, X-Frame-Options

---

🆘 Troubleshooting

Permission Errors

# Run the permission fix
./scripts/setup_permission_fix.sh

# Or manually:
sudo chown -R $USER:$USER /mnt/HC_Volume_*/podman-root

502 Bad Gateway

# Check if pod is running
podman pod ps

# Restart Caddy
systemctl --user restart caddy.service

# Check network DNS
podman exec caddy-pod-caddy getent hosts <pod-name>

Service Won't Start

# Check systemd logs
journalctl --user -u <service>.service -n 50

# Check container logs
podman logs <container-name>

After Reboot Issues

The fix-podman-permissions.service runs automatically. If issues persist:

./scripts/setup_permission_fix.sh

---

📚 Documentation

Document	Description
SETUP.md	Complete setup guide
docs/ARCHITETTURA.md	Architecture details (Italian)

---

📄 License

MIT License

---

Created by Simone Miglio 🇮🇹