Homelab

Source-of-truth for a Proxmox-based homelab: Ansible playbooks and roles to create LXC/VM guests and deploy services.

Prerequisites

• Ansible installed (brew install ansible on macOS or pip install ansible-core)
• Access to the Proxmox API and target hosts
• Create vars files in vars/ (see vars/*.example)

Deploy Commands

Run from the project root. Some playbooks require a vars file via -e "@vars/<name>_vars.yml".

Infrastructure

Create LXC containers (Proxmox):

ansible-playbook deployments/create_lxc.yml -e "@vars/proxmox_create_vars.yml"

Destroy LXC containers:

ansible-playbook deployments/destroy_lxc.yml -e "@vars/proxmox_create_vars.yml"
ansible-playbook deployments/destroy_lxc.yml -e "@vars/proxmox_create_vars.yml" -e "vmid=253"  # single container

Playbooks

AdGuard Home (DNS+DHCP):

ansible-playbook deployments/deploy_adguard.yml

Caddy (reverse proxy + Cloudflare Tunnel):

ansible-playbook deployments/deploy_caddy.yml -e "@vars/caddy_vars.yml"

PocketID (identity + Tinyauth):

ansible-playbook deployments/deploy_pocketid.yml -e "@vars/pocketid_vars.yml"

HashiCorp Vault (secrets management):

ansible-playbook deployments/deploy_vault.yml

Configure Vault (kv-v2, AppRole, OIDC, policies):

ansible-playbook deployments/configure_vault.yml -e "vault_token=<root-token>" -e "@vars/vault_config_vars.yml"

PostgreSQL (database server):

ansible-playbook deployments/deploy_postgresql.yml -e "@vars/vault_auth_vars.yml" -e "@vars/postgresql_apps.yml"

MySQL (database server):

ansible-playbook deployments/deploy_mysql.yml -e "@vars/vault_auth_vars.yml" -e "@vars/mysql_apps.yml"

Redis (in-memory data store):

ansible-playbook deployments/deploy_redis.yml -e "@vars/vault_auth_vars.yml"

MongoDB (document database):

ansible-playbook deployments/deploy_mongodb.yml -e "@vars/vault_auth_vars.yml" -e "@vars/mongodb_apps.yml"

Monitoring (Prometheus + Grafana):

ansible-playbook deployments/deploy_monitoring.yml -e "@vars/vault_auth_vars.yml"

Node Exporter (metrics agent on all hosts):

ansible-playbook deployments/deploy_node_exporter.yml

PVE Exporter (Proxmox VE metrics):

ansible-playbook deployments/deploy_pve_exporter.yml -e "@vars/vault_auth_vars.yml"

Jellyfin (media server):

ansible-playbook deployments/deploy_jellyfin.yml

ARR stack (Radarr, Sonarr, SABnzbd, etc.):

ansible-playbook deployments/deploy_arr.yml

Immich (photo/video backup):

ansible-playbook deployments/deploy_immich.yml -e "@vars/vault_auth_vars.yml"

Uses central PostgreSQL and Redis. Ensure immich user/db exist (in postgresql_apps), PostgreSQL has pgvector, and Vault kv/homelab/data/postgresql has key immich (db password).

OIDC (PocketID) login: create client at https://id.mol.la/settings/admin/oidc-clients with redirect URIs https://photos.mol.la/auth/login, https://photos.mol.la/user-settings, app.immich:///oauth-callback; then vault kv put kv/homelab/data/immich_oidc client_id="..." client_secret="..."

After deploying a new service that Caddy should proxy, redeploy Caddy to update routes. After adding a new LXC, run deploy_node_exporter.yml and add the host to prometheus_scrape_jobs in the monitoring role defaults, then redeploy monitoring.

---