Deployment Overview of Proxmox VE on Server¶

This document provides the technical deployment specifications for Proxmox Virtual Environment (VE) on a Debian-based system. The installation includes the Proxmox kernel, core virtualization packages, and an Nginx reverse proxy container with automated SSL management via Certbot.

Prerequisites and Basic Requirements¶

The following requirements must be met prior to or during the installation process:

Operating System: Debian (versions 11 Bullseye, 12 Bookworm, or 13 Trixie are supported).
Privileges: Root or sudo access is required for all package management and system configuration tasks.
Network: An active internet connection is required to fetch repositories and SSL certificates.
Disk Configuration: The installation assumes the bootloader (GRUB) is targeted at /dev/sda.

FQDN of the final panel on the hostkey.in domain¶

The management interface is accessible via a specific subdomain template based on the unique Server ID.

Parameter	Value
Prefix	`proxmox`
Domain	`hostkey.in`
Full template	`proxmox{Server_ID}.hostkey.in`

File and Directory Structure¶

The deployment utilizes specific directories for configuration and data persistence:

/etc/apt/sources.list.d/pve-install-repo.list: Proxmox VE repository configuration.
/data/nginx/user_conf.d/: Custom Nginx configuration files for the reverse proxy.
/data/nginx/letsencrypt/: Webroot directory for ACME challenges (Certbot).
/data/nginx/nginx-certbot.env: Environment variables for the Nginx container.
/root/nginx/compose.yml: Docker Compose file for the Nginx service.

Application installation process¶

The installation is performed through a multi-stage process involving system updates, kernel replacement, and package management:

System Preparation: The system performs a full distribution upgrade (apt upgrade --dist) and ensures all APT timers are active.
Repository Configuration:
The Proxmox VE repository is added to the APT sources.
The corresponding GPG security keys for Debian Bullseye, Bookworm, or Trixie are installed into /etc/apt/trusted.gpg.d/.
Kernel Replacement:
The standard Debian kernel is removed and replaced with the Proxmox VE optimized kernel (pve-kernel or proxmox-default-kernel depending on the OS version).
GRUB bootloader configuration is updated via update-grub.
Core Software Installation:
The proxmox-ve package is installed along with postfix (for mail services) and open-iscsi (for storage connectivity).
Docker Engine Setup: Docker is installed to manage the reverse proxy container. On specific Debian versions, a custom systemd service configuration is applied to ensure proper cgroup delegation.

Access Rights and Security¶

Firewall/Network: The application uses port 443 (HTTPS) for external access and port 8006 (HTTPS) for the internal Proxmox management interface.
Security Hardening:
The os-prober package is removed to prevent unauthorized bootloader scanning.
Enterprise repositories are commented out by default to ensure compatibility with non-subscription environments.

Docker Containers and Their Deployment¶

The deployment utilizes a single containerized service to handle SSL termination and reverse proxying.

Service Name	Image	Ports	Volumes	Environment Variables	Restart Policy
`nginx`	`jonasal/nginx-certbot:latest`	Host Network Mode	`nginx_secrets:/etc/letsencrypt` `/data/nginx/user_conf.d:/etc/nginx/user_conf.d` `/data/nginx/letsencrypt:/var/www/letsencrypt`	`[email protected]`	`unless-stopped`

Custom Scripts and Additional Setup¶

The deployment includes several automated configuration steps:

Nginx Configuration Patching: A Python script is executed to automatically inject ACME challenge locations (/.well-known/acme-challenge/) into the Nginx server blocks. It also configures proxy_pass to point to https://127.0.0.1:8006 and enables proxy_ssl_server_name on; and proxy_ssl_verify off; to allow secure communication with the Proxmox backend.
Certbot Automation: The deployment configures a renewal interval of 8 days within /data/nginx/nginx-certbot.env.

Application Update Instructions¶

To update the main application:

System Packages: Run apt update && apt full-upgrade to apply Proxmox kernel and system updates.
Docker Services: To update the Nginx proxy, navigate to /root/nginx and execute:
```
docker compose pull && docker compose up -d
```

Location of configuration files and data¶

Proxmox Configuration: Standard Proxmox paths within /etc/pve.
Nginx Proxy Configs: /data/nginx/user_conf.d/
SSL Certificates: Managed via the nginx_secrets Docker volume.

Available ports for connection¶

443 (HTTPS): External access to the web interface via the configured FQDN.
8006 (HTTPS): Internal management port for Proxmox VE.

Starting and Stopping the application¶

Proxmox Services: Managed via standard systemctl commands (e.g., systemctl status pveproxy).
Nginx Proxy:
Start/Restart: docker compose up -d from /root/nginx.
Stop: docker compose down from /root/nginx.