This project automates a full homelab deployment — Packer builds the VM template, Terraform provisions it on Proxmox, and Ansible handles everything inside: Docker, Portainer, Traefik, and optional services like a media stack and Homepage dashboard.

Requirements

Architecture and Source Code

Source: meroxdotdev/homelab-as-code

What’s in the Repository

The repo covers everything needed to go from zero to a running VM with services:

• Deploy script — installs dependencies (git, curl, ansible, packer, terraform), clones the repo, and runs the full pipeline
• ansible/ — roles for Docker, Portainer, Traefik, and optional NFS mounts
• configs/docker/ — pre-configured services: Homepage, Traefik, media stack
• packer/ — builds an optimized Ubuntu template for Proxmox
• terraform/ — VM provisioning with networking and storage, based on the Packer template

Quick Start

Run this on a clean LXC:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/meroxdotdev/homelab-as-code/refs/heads/master/deploy_homelab.sh)"

What the Script Does

The script first asks whether your repository is public or private. For private repos, it generates an SSH key and prompts you to add it as a deploy key in your repo settings. For the public tutorial repo, use https://github.com/meroxdotdev/homelab-as-code.git directly.

Next, it asks whether you’ve already edited the required config files. Type yes to proceed with the Packer → Terraform → Ansible pipeline, or no to exit and review the guides below first.

Downloaded config files land in /home/homelab/.

Configuration Guides

The setup is split across four subposts — go through them in order before running the script:

1. Ansible Setup — inventory, roles, optional NFS mounts
2. Services Configuration — Homepage, Media Stack, Traefik
3. Infrastructure Setup — Packer and Terraform
4. Deployment & Verification — final steps and checks

This covers the Ansible side of the homelab automation — inventory generation, service roles, and optional NFS mount configuration.

Inventory

The inventory folder holds the inventory.ini file that maps the VM’s IP and SSH credentials for Ansible. You don’t touch this manually — Terraform generates it automatically during deployment:

1
resource "local_file" "ansible_inventory" {
2
  depends_on = [time_sleep.wait_1_minute]
3

4
  content = <<EOT
5
[docker]
6
docker-01 ansible_host=IP_DEPLOYMENT ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_rsa
7
EOT
8

9
  filename = "../ansible/inventory/inventory.ini"
10
}

Roles

The roles/docker folder contains playbooks for installing and configuring Docker, Docker Compose, Portainer, Homepage, and Traefik. Each service has its own .yml file.

NFS Mount (Optional)

If you’re mounting an external NFS share, edit roles/nfs_mount with your values.

Replace the NFS server address:

REPLACE_this_with_your_nfs_server_ip_address

Replace the share path:

REPLACE_this_with_your_nfs_path

The final line should look like this:

172.20.0.254:/volume1/Server/Data/media_nas/ /media nfs rw,hard,intr 0 0

Next Steps

Proceed to the Services Configuration guide.

This covers the Docker service configuration — Homepage, Media Stack, and Traefik.

Homepage

No edits needed in /docker/homepage/. If you want to bring an existing config, extract the archive, drop your files in, and re-archive. After deployment, the config is available on the VM at /home/homepage/.

Media Stack

In /docker/media-stack/, update the Host rules in the labels section to match your domain or local DNS entries (Pi-hole, Unbound, Technitium, etc.):

1
- "traefik.http.routers.jellyseer-media.rule=Host(`jellyseer.local`)"

Replace with your domain:

1
- "traefik.http.routers.jellyseer-media.rule=Host(`jellyseer.merox.cloud`)"

Do this for every service in the stack.

Traefik

Two options: edit after deployment (configs land in /home/traefik/ on the VM), or extract the archive, edit locally, and re-archive before running the script.

docker-compose.yaml — replace all four occurrences of yourdomain.com with your actual domain. Provider used is Cloudflare.

.env — sets credentials for the Traefik dashboard. Defaults are user / password. Change these.

data/config.yml — optional. Use this to expose non-Docker services over SSL, like your Proxmox UI at proxmox.mydomain.com.

data/traefik.yml — replace your-cloudflare@email.com with your Cloudflare account email.

Start Traefik manually after creating the token file:

/usr/local/bin/docker-compose up &

For more on Traefik, see this detailed guide.

Next Steps

Proceed to the Infrastructure Setup guide to configure Packer and Terraform.

This covers Packer and Terraform configuration for building the VM template and provisioning infrastructure on Proxmox.

Packer

API Credentials

Holds your Proxmox API credentials. Do not commit this to a public repository.

1
proxmox_api_url          = "https://your-proxmox-ip-or-fqdn/api2/json"
2
proxmox_api_token_id     = "terraform_user@pam!homelab"
3
proxmox_api_token_secret = "your-proxmox-api-token-secret"

To generate a Proxmox API token: tutorial. More Packer examples: here.

Plugin Configuration

Plugin configuration for the Proxmox provider:

1
packer {
2
  required_plugins {
3
    proxmox-iso = {
4
      version = ">= 1.0.0"
5
      source  = "github.com/hashicorp/proxmox"
6
    }
7
  }
8
}

VM Template Definition

Replace YOUR_PROXMOX_NODE_NAME with your Proxmox node name and YOUR_IP_DEPLOYMENT_MACHINE with the IP of the machine running the deploy script.

Cloud-Init User Data

Replace YOUR_SSH_KEY with the SSH key generated by homelab_deploy.sh.

Terraform

Credentials and Variables

Holds credentials for Proxmox. Do not commit this to a public repository.

1
proxmox_api_url          = "https://your-proxmox-ip-or-fqdn/api2/json"
2
proxmox_api_token_id     = "terraform_user@pam!homelab"
3
proxmox_api_token_secret = "your-proxmox-api-token-secret"
4
proxmox_host             = "proxmox-host-ip"
5
proxmox_user             = "proxmox-user"
6
proxmox_password         = "proxmox-password"

VM Module Configuration

Replace all placeholders with your values:

• YOUR_PROXMOX_NODE_NAME
• IP_MACHINE — VM deployment IP
• GateWay_IP
• IP_DEPLOYMENT — same as IP_MACHINE
• YOUR_SSH_KEY — generated by homelab_deploy.sh

If you’re not using NFS, comment out this block:

1
resource "null_resource" "run_ansible_docker" {
2
  depends_on = [local_file.ansible_inventory]
3

4
  provisioner "local-exec" {
5
    command = "LC_ALL=C.UTF-8 LANG=C.UTF-8 ansible-playbook -i ../ansible/inventory/inventory.ini ../ansible/roles/nfs_mount/main.yml"
6
  }
7
}

Other things configured in this file: locales, root SSH login, SSH key auth, and the Ansible integration trigger.

Next Steps

Proceed to the Deployment guide.

Deployment Output

A successful deployment will produce output like this:

Accessing Portainer

Once done, Portainer is available at port 9000 on your VM’s IP:

1
http://172.20.0.252:9000

Set up your Portainer user and you should see a dashboard similar to the one above.

If you run into issues, leave a comment and I’ll take a look.