Proxmox Practice Lab

A hands-on, end-to-end learning path for Proxmox VE — from a fresh install to fully automated infrastructure. A bilingual (EN/FR) 14-chapter manual explains the why, a local dashboard tracks your progress, and real Terraform + Ansible artifacts let you practice for real.

This repository is built for people who want to understand Proxmox, not just copy commands. Every chapter states the technical decision, its prerequisites, the hands-on steps, the validation you should observe, and the common mistakes to avoid. The dashboard ("cockpit") gives the big-picture progress view; the manual gives the reasoning; the infra/ folder gives the runnable, production-shaped code.

Highlights

• Structured curriculum — beginner → expert++, chapter by chapter, with a required proof before moving on.
• Bilingual manual — full English (docs/en) and French (docs/fr) versions kept in sync.
• Real Infrastructure as Code — Terraform (bpg/proxmox provider) and Ansible playbooks you actually run.
• Local progress cockpit — a TanStack Start dashboard, no access to your Proxmox and no secrets required.
• Secure by default — dedicated API tokens, least privilege, gitignored state/inventory, tested restores.

Tech stack

TanStack Start · React 19 · Vite · Tailwind CSS · shadcn/ui · Drizzle ORM · SQLite (better-sqlite3) · Terraform · Ansible · Docker · Caddy · Tailscale · Cloudflare Tunnel & Access.

Getting started

Start with chapter 00, then launch the local cockpit:

bun install
bun run dev

Open the URL printed by Vite. The interface never connects to your Proxmox node, and no secret should ever be entered into the project.

Learning path

The manual index organizes the curriculum from beginner to expert++. Each chapter covers the technical decision, prerequisites, practice, validation, and common pitfalls.

Level	Chapter	Validated skill
Beginner	Post-installation	Readable node, safe access, documented initial state
Beginner	Network, storage, access	Network path, content types, basic ACLs
Confirmed	LXC — first service	Nginx service in an unprivileged LXC
Confirmed	VM & cloud-init	Clonable template, working SSH and QEMU agent
Senior	Remote access & devbox	Private Tailscale, local Caddy, cloudflared behind Access
Senior	Backup & DR	Defined RPO/RTO, restore actually tested
Expert++	Terraform & Ansible	Declarative infra and idempotent config
Expert++	Terraform / Ansible A→Z	Full lifecycle, state, drift, and the complete pipeline

Infrastructure artifacts

• infra/terraform — cloud-init VM clone using the community bpg/proxmox provider (expects an existing cloud-init template):

  cd infra/terraform
  cp terraform.tfvars.example terraform.tfvars
  terraform init
  terraform fmt -check
  terraform validate
  terraform plan

  terraform.tfvars is gitignored. Use a dedicated, least-privilege API token — never root@pam in a script.

• infra/ansible — native Nginx app (site.yml) and a single-node Docker Swarm stack in a guest VM (docker.yml):

  cd infra/ansible
  ansible-galaxy collection install -r requirements.yml
  cp inventory.example.yml inventory.yml
  ansible-playbook -i inventory.yml site.yml --check --diff
  ansible-playbook -i inventory.yml site.yml

• infra/remote-dev — a devtools VM with code-server, a private Docker preview, and an optional Cloudflare profile. Tailscale is the default path for administration; Cloudflare Access is the targeted path to share a web preview.

Security checks before apply

• Verify the target node and storage.
• Read the terraform plan or the Ansible --check --diff output.
• Never commit tokens, private keys, real inventories, or Terraform state.
• Test a real restore in an isolated network before trusting any backup.

References

• Proxmox VE Administration Guide — API tokens and ACLs.
• BPG Terraform provider for Proxmox — compatibility notes and VM configuration.
• Ansible community.proxmox collection — the specialized collection replacing the old community.general path.
• Tailscale SSH & Tailscale Serve — administration and private previews.
• Cloudflare Tunnel & Cloudflare Access — explicitly protected web publishing.

License

MIT — see LICENSE.