Setup scripts and documentation for a Proxmox-based homelab environment. This repository contains automated, auditable setup scripts and detailed documentation for building a secure, repeatable, and production-style homelab.
This project is designed to provide a clean baseline for:
- Proxmox VE hosts
- Debian and Ubuntu virtual machines
- Secure SSH access and network controls
- Optional Docker-based workloads
- Homelab environments that prioritize clarity, safety, and repeatability
All scripts are designed to be:
- Safe to re-run
- Explicit about changes
- Transparent before making risky modifications
- Easy to audit and revert
proxmox-homelab/
├── .gitignore
├── LICENSE
├── README.md
└── scripts/
├── cli-tools/
│ └── ai-tools/
│ ├── ai-tools.sh
│ └── README.md
├── docker-compose/
│ ├── admin-tools/
│ │ ├── .env.example
│ │ ├── docker-compose.yml
│ │ └── README.md
│ └── llm-chat/
│ ├── .env.example
│ ├── docker-compose.yml
│ ├── README.md
│ └── settings.yml
├── proxmox-setup/
│ ├── proxmox-setup.sh
│ └── README.md
└── vm-setup/
├── debian-setup.sh
├── ubuntu-setup.sh
└── README.md
Location: scripts/proxmox-setup/proxmox-setup.sh
Purpose:
- Establish a clean and secure Proxmox VE baseline
- Reduce noise from enterprise-only features
- Add basic SSH protection
Key features:
- Verifies the system is a Proxmox VE host before running
- Optionally runs the community-maintained Proxmox post-install script
- Previews the community script before execution and requires confirmation
- Optionally installs and configures Fail2Ban for SSH protection
- Tracks and reports failed steps without stopping execution
Important behavior:
- Skipping the community script or Fail2Ban is treated as intentional, not an error
- Designed to be safe to re-run
- Intended to be run on the Proxmox host itself, not inside a VM
See scripts/proxmox-setup/README.md for full details.
Location: scripts/vm-setup/
Separate scripts are maintained for Debian and Ubuntu to account for OS-specific differences without relying on conditional logic.
Scripts:
ubuntu-setup.shdebian-setup.sh
Purpose:
- Provide a consistent, secure baseline for new VMs
- Integrate cleanly with Proxmox
Shared behavior across both scripts:
- Installs QEMU guest agent for Proxmox integration
- Installs a minimal, practical set of baseline packages
- Hardens SSH using drop-in configuration files
- Enables unattended security updates
- Applies small, safe system performance tweaks
- Continues execution even if individual steps fail
- Produces a clear completion summary and optional log file
Optional features (opt-in via flags):
- UFW firewall with subnet-restricted SSH access
- Docker Engine via the official Docker repository
- Sudo password feedback
- Persistent log file retention
See scripts/vm-setup/README.md for full usage examples and explanations.
Location: scripts/docker-compose/admin-tools/
Purpose:
- Centralized administration and productivity tools
- Container monitoring and automated update checking
- Self-hosted password management
- Docker Compose stack management
- Developer utilities and PDF processing
Key features:
- Watchtower for container update monitoring
- Dockge web UI for managing Docker Compose stacks
- Vaultwarden for password management
- IT-Tools collection for developer utilities
- Stirling PDF for document processing
The stack requires Docker and Docker Compose.
See scripts/docker-compose/admin-tools/README.md for complete setup guide.
Location: scripts/docker-compose/llm-chat/
Purpose:
- Provide a complete local AI workspace with privacy and control
- Run powerful language models on your own hardware
- Enable web search capabilities for AI responses
- Eliminate API costs and data sharing with cloud providers
Key features:
- Ollama for local LLM inference
- Lobe Chat as a modern web interface
- SearXNG for privacy-focused web search integration
- Valkey for search result caching
- Complete Docker Compose stack for easy deployment
- All data stays local on your machine
The stack requires having Docker installed.
See scripts/docker-compose/llm-chat/README.md for complete setup instructions and usage guide.
- Root login is disabled
- Configuration is applied using
/etc/ssh/sshd_config.d/drop-in files - The main SSH configuration file is never modified
- Password authentication remains enabled by default for safety and initial access
- Additional hardening options are provided but commented out
- UFW is opt-in only
- Firewall rules are displayed before being applied
- SSH is restricted to a specific subnet when enabled
- Subnets are validated and auto-detected where possible
- Broad subnets trigger explicit warnings and confirmation prompts
- The script displays the current connection IP to help prevent lockouts
- Installed only when explicitly requested
- Uses Docker's official apt repository
- Avoids convenience scripts for better auditability
- Adds the invoking user to the docker group
- Does not assume immediate logout or reboot
- Scripts do not abort on the first failure
- All failed steps are tracked and reported at the end
- Logs are automatically saved when failures occur
- This behavior is intentional to avoid partial configuration states
- Install Proxmox VE
- SSH or log in locally
- Run
proxmox-setup.sh - Review output and reboot if kernel or system packages were updated
- Create VM in Proxmox
- Install Debian or Ubuntu
- SSH into the VM
- Run the matching VM setup script
- Enable firewall and Docker only when ready
This project is open source and available under the MIT License.
- These scripts were designed for homelab environments, not production enterprise systems
- Always review scripts before running them with root privileges
- Test in a non-critical environment first
- Backup important data before running any automation scripts
- Running them twice is safe, but you should still test them on a fresh install first.