https://github.com/borjaip/homelab
🧬 Homelab 🖥
https://github.com/borjaip/homelab
arr docker homelab homelab-automation homelab-media homelab-setup k8s kubernetes packer proxmox terraform traefik
Last synced: about 1 month ago
JSON representation
🧬 Homelab 🖥
- Host: GitHub
- URL: https://github.com/borjaip/homelab
- Owner: BorjaIP
- Created: 2025-05-14T20:58:28.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-31T22:32:54.000Z (about 1 year ago)
- Last Synced: 2025-07-03T19:46:01.039Z (11 months ago)
- Topics: arr, docker, homelab, homelab-automation, homelab-media, homelab-setup, k8s, kubernetes, packer, proxmox, terraform, traefik
- Language: HCL
- Homepage:
- Size: 74.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Homelab
A fully automated, themed homelab built with Proxmox, Terraform, and Docker.
---
- [🔧 System Configuration](#-system-configuration)
- [🔑 SSH Key \& Certificate Generation](#-ssh-key--certificate-generation)
- [🌐 Proxy Configuration (Traefik)](#-proxy-configuration-traefik)
- [📁 NFS Configuration](#-nfs-configuration)
- [Optional - Share Storage](#optional---share-storage)
- [1. Install NFS Server](#1-install-nfs-server)
- [2. Add NFS Storage to Proxmox](#2-add-nfs-storage-to-proxmox)
- [🧱 Base VMs with Packer](#-base-vms-with-packer)
- [🚀 VM Deployment with Terraform](#-vm-deployment-with-terraform)
- [⚙️ Configuration](#️-configuration)
- [Transmission and OpenVPN](#transmission-and-openvpn)
- [Home Assistant](#home-assistant)
- [Windows Share with Rclone](#windows-share-with-rclone)
- [🔗 References](#-references)
This homelab infrastructure is centered on **Proxmox VE** using **Terraform** and **Docker** to provision VMs and Dockers (*names based in the Angels from Neon Genesis Evangelion*). Each VM serves a specific purpose like media, storage, or network automation.
## 🔧 System Configuration
> Refer to the table below for an at-a-glance view of each configured and planned virtual machine and its corresponding role.
These steps are tailored specifically to my homelab infrastructure. Some assumptions are made (like Proxmox being pre-installed), and tools are selected based on personal preference and workflow. Your configuration may vary depending on your hardware, network design, and requirements.
- [Proxmox VE](https://proxmox.com/en/products/proxmox-virtual-environment/get-started) is already installed and fully configured in this environment.
- Create new SSH Key for setup conectivity.
- Use [Proxmox VE Helper Scripts](https://community-scripts.github.io/ProxmoxVE/) for community-contributed helper scripts for VM management, backups, and more.
- Setup [Traefik](https://github.com/traefik/traefik) as a reverse proxy to handle and redirect HTTP/S traffic.
## 🔑 SSH Key & Certificate Generation
Generate an SSH key for your vm's or other services:
```bash
ssh-keygen -t ed25519 -C "server"
```
Use the generated public key in `user-data` for automatic authentication setup.
## 🌐 Proxy Configuration (Traefik)
Using [traefik-kop](https://github.com/jittering/traefik-kop), each VM runs an agent that:
- Registers itself with the main Traefik instance
- Sends its routing configuration dynamically
This enables:
- Auto-discovery of services
- Clean URLs and HTTPS support
- Centralized control over routing logic
```text
+-------------------------+ +---------------------0----+
| +---------------------+ | | +---------------------+ |
| | | | | | | |
+---------+ :443 | | +---------+ | | :8088 | | +------------+ | |
| WAN |--------------->| traefik |<-------------------->| | svc-nginx | | |
+---------+ | | +---------+ | | | | +------------+ | |
| | | | | | | | |
| | +---------+ | | | | +-------------+ | |
| | | redis |<-------------------->| | traefik-kop | | |
| | +---------+ | | | | +-------------+ | |
| | docker1 | | | | docker2 | |
| +---------------------+ | | +---------------------+ |
| vm1 | | vm2 |
+-------------------------+ +--------------------------+
```
## 📁 NFS Configuration
### Optional - Share Storage
> [!Note]
> ⚠️ NTFS support is functional but comes with performance and permission caveats—consider ext4/ZFS for native setups.
To consolidate data across VMs, I export a shared storage path via NFS, backed by an NTFS-formatted disk. While not typical in Linux-first setups, this suits my personal needs.
```bash
sudo apt install -y ntfs-3g
```
List all the devices and select which one you need to mount.
```bash
sudo fdisk -l
sudo lsblk -f
ls -l /dev/disk/by-uuid/
```
Copy the UUID in /etc/fstab
```bash
# edit fstab
vim /etc/fstab
UUID="" /mnt/storage ntfs-3g defaults,auto 0 0
mkdir /mnt/storage
# mount disc
mount -a
```
- Add disk to VM.
```bash
ls -l /dev/disk/by-id/
qm set 103 -virtio2 /dev/disk/by-id/
```
### 1. Install NFS Server
```bash
sudo apt install -y nfs-kernel-server
sudo vim /etc/exports
```
Example export entry:
```bash
/mnt/storage 192.168.1.0/24(rw,sync,no_subtree_check)
```
> - Replace 192.168.1.0/24 with the subnet of your Proxmox server (e.g., 192.168.1.0/24 allows all IPs in the 192.168.1.x range).
> - rw: Allows read and write access.
> - sync: Ensures changes are written to disk before the client is notified.
> - no_subtree_check: Prevents subtree checking for better performance.
### 2. Add NFS Storage to Proxmox
1. Login to Proxmox Web UI
2. Navigate to `Datacenter > Storage > Add > NFS`
3. Fill in:
* **ID**: Enter a name for the storage (e.g., nfs-storage).
* **Server**: Enter the IP address of the NFS server (e.g., 192.168.1.111).
* **Export**: Click Query to list available NFS exports, and select /mnt/storage.
* **Content**: Select the types of content you want to store (e.g., Disk image, ISO image, Backup).
* **Nodes**: Select the Proxmox nodes that can access this storage.
## 🧱 Base VMs with Packer
> [!Warning]
> ⚠️ To be able to run packer from WSL2 you need to change the network mode.
All virtual machines are built from a [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html) Ubuntu 24.04 image using Packer. This ensures consistency across deployments.
Configure `variables.auto.pkrvars.hcl` file for custom values.
```bash
cd packer
packer validate .
packer build .
```
- The resulting image is uploaded to Proxmox as a VM template.
- Cloud-init is enabled in the build to support dynamic configuration.
- Include Docker installation an other tools.
- This template is later used by Terraform to deploy actual VMs.
## 🚀 VM Deployment with Terraform
Deploy or destroy VMs using Terraform's targeted apply.
Ensure that your `terraform.tfvars` and modules are configured per [Proxmox Provider](https://registry.terraform.io/providers/Telmate/proxmox/latest/docs) standards.
```bash
cd terraform
terraform plan
terraform apply
# or
terraform apply -target='module.vms["ramiel"]'
terraform destroy -target='module.vms["ramiel"]'
```
📦 VMs
Thumbnail
VM Name
ID
Category
Services/Tools
Adam
201
Proxmox Host
Proxmox VE
Lilith
202
Storage
TrueNAS*
Sachiel
203
Media Server
Plex / Jellyfin / Plextraktsync / Navidrome
Shamshel
204
Arr Stack
Sonarr / Radarr / Lidarr / Prowlarr / Overseerr
Ramiel
205
Downloaders
Transmission
Gaghiel
206
Reverse Proxy and Tunnels
Traefik / CloudflareTunnels
Israfel
207
NFS Server
NFS*
Sandalphon
208
Network tools
Gluetun / Flaresolverr
Matarael
209
Dashboards
Homepage / Homarr / Homer
Sahaquiel
210
Monitoring
Uptimekuma / Dozzle
Ireul
211
Utilities
Home Assistant / Immich / Paperless
[*]: *Future changes or upgrades.*
## ⚙️ Configuration
### Transmission and OpenVPN
- For testing Transmission with OpenVPN add this torrent from [TorGuard](https://torguard.net/checkmytorrentipaddress.php?hash=f1f5bda133bdbb4743773cc8548cbaee1fbff88a).
### Home Assistant
- Setup [HACS](https://hacs.xyz/docs/use/download/download/)
- Setup IKEA [Dirigera](https://github.com/sanjoyg/dirigera_platform)
### Windows Share with Rclone
- Install [Rclone](https://rclone.org/install/)
```bash
# Installing
winget install --id=Rclone.Rclone -e
# Setup new SFTP connection
rclone config
# Show all volumes
rclone listremotes
# Mount
rclone mount nas:/mnt/storage X: --vfs-cache-mode full --vfs-cache-max-size 2G --vfs-read-chunk-size 64M --vfs-read-chunk-size-limit 512M --buffer-size 32M --attr-timeout 1s --no-modtime --network-mode --dir-cache-time 5m --poll-interval 10s --log-level INFO
```
- Copy files
```bash
rclone copy "F:/" nas:"/mnt/storage/backup/" --progress
```
## 🔗 References
* [Proxmox Packer Templates](https://github.com/sdhibit/packer-proxmox-templates)
* [Terraform Cloud-Init VM](https://github.com/sdhibit/terraform-proxmox-cloud-init-vm)
* [Telmate Terraform Provider](https://github.com/Telmate/terraform-provider-proxmox)
* [Proxmox Ubuntu Templates](https://github.com/bcochofel/packer-proxmox-ubuntu)
* [Proxmox-VM-Disk-and-NFS-Configuration-Guide](https://github.com/Ayman92M/Proxmox-VM-Disk-and-NFS-Configuration-Guide)
* [Evangelion Angel Wiki](https://wiki.evageeks.org/Angels)
---
✦ Inspired by Evangelion. Built for learning, automation, and chaos. ✦