From 7290304d5fe56e16f2f09ec1b1d67a89848f16bf Mon Sep 17 00:00:00 2001 From: Michael Schapira - krilin Date: Wed, 12 Nov 2025 22:12:47 -0500 Subject: [PATCH] proxmox deployement --- PROXMOX-DEPLOYMENT.md | 332 +++++++++++++++++++++++++++++++++ proxmox-deployment-config.yaml | 204 ++++++++++++++++++++ 2 files changed, 536 insertions(+) create mode 100644 PROXMOX-DEPLOYMENT.md create mode 100644 proxmox-deployment-config.yaml diff --git a/PROXMOX-DEPLOYMENT.md b/PROXMOX-DEPLOYMENT.md new file mode 100644 index 0000000..d3b344b --- /dev/null +++ b/PROXMOX-DEPLOYMENT.md @@ -0,0 +1,332 @@ +# Proxmox LXC Deployment Guide + +This guide will help you deploy the QR Code Generator application as an LXC container on Proxmox. + +## Quick Start + +### Step 1: Fill Out Configuration + +Edit the `proxmox-deployment-config.yaml` file with your Proxmox environment details: + +```bash +nano proxmox-deployment-config.yaml +``` + +### Step 2: Minimum Required Fields + +At minimum, you need to configure: + +1. **Proxmox Host Information**: + - `proxmox.host` - Your Proxmox server IP + - `proxmox.node` - Proxmox node name (usually "pve") + +2. **Container Settings**: + - `lxc.vmid` - Unique container ID (e.g., 200) + - `lxc.hostname` - Container hostname + +3. **Network**: + - `network.bridge` - Network bridge (usually "vmbr0") + - `network.ip_method` - Choose "dhcp" or "static" + - If static, fill in `ip_address`, `gateway`, `nameserver` + +4. **Authentication** (choose one): + - Option A: API Token (recommended) + - `proxmox.api_token_id` + - `proxmox.api_token_secret` + - Option B: Username/Password + - `proxmox.username` + - `proxmox.password` + +### Step 3: Run Deployment + +Once the configuration file is complete, run: + +```bash +# The deployment script will be generated based on your config +./deploy-to-proxmox.sh +``` + +## Configuration Sections Explained + +### 1. Proxmox Host Configuration + +This section defines how to connect to your Proxmox server. + +**Getting API Token** (Recommended): +1. Log into Proxmox web UI +2. Go to Datacenter → Permissions → API Tokens +3. Click "Add" to create a new token +4. Save the Token ID and Secret + +**Alternative**: Use username/password (less secure) + +### 2. LXC Container Configuration + +- **VMID**: Must be unique across your Proxmox cluster + - To check used IDs: `pvesh get /cluster/resources --type vm` + - Typically use 100-999 for containers + +- **Template**: Available templates + - List available: `pveam available | grep -i ubuntu` + - Download template: `pveam download local ubuntu-22.04-standard_22.04-1_amd64.tar.zst` + +- **Unprivileged**: Recommended for security + - `true` = safer, limited permissions + - `false` = full root access (needed for some operations) + +### 3. Resource Allocation + +Recommended minimum for this application: +- Memory: 1024 MB (can go up to 2048 MB for better performance) +- Cores: 1-2 +- Disk: 8-10 GB + +### 4. Network Configuration + +**DHCP** (Easier): +- Set `ip_method: dhcp` +- Container gets IP automatically from your router + +**Static IP** (Better for production): +- Set `ip_method: static` +- Fill in IP address with CIDR notation (e.g., 192.168.1.150/24) +- Set gateway (usually your router IP) +- Set nameserver (DNS server, e.g., 8.8.8.8) + +**Finding your network settings**: +```bash +# On Proxmox host +ip addr show vmbr0 +ip route | grep default +``` + +### 5. Application Configuration + +- **Port 8501**: Default Streamlit port + - Can change if needed + - Make sure this port is not in use + +- **Git Repository**: + - Leave empty to copy files from local directory + - Or provide GitHub/GitLab URL to clone from repository + +### 6. Reverse Proxy & SSL (Optional) + +Enable this if you want: +- HTTPS access +- Custom domain name +- Automatic SSL certificates via Let's Encrypt + +Requirements: +- Domain name pointing to your Proxmox host +- Port 80 and 443 accessible from internet (for Let's Encrypt) + +### 7. Security & Access + +**SSH Key** (Recommended): +1. Generate key: `ssh-keygen -t rsa -b 4096` +2. Copy your public key: `cat ~/.ssh/id_rsa.pub` +3. Paste into `ssh_public_key` field + +**Firewall**: +- Set `configure_firewall: true` to restrict access +- Specify `allowed_ips` to limit who can access + +## Deployment Methods + +### Method 1: Shell Script (Recommended for Beginners) + +Simple bash scripts that: +- Create the LXC container +- Install dependencies +- Deploy the application +- Set up systemd service + +**Pros**: Easy to understand and modify +**Cons**: Less sophisticated than IaC tools + +### Method 2: Terraform + +Infrastructure as Code approach: +- Declarative configuration +- State management +- Easy to replicate + +**Pros**: Professional, repeatable, version-controlled +**Cons**: Requires Terraform installation + +### Method 3: Ansible + +Configuration management: +- Powerful automation +- Idempotent operations +- Great for multiple deployments + +**Pros**: Flexible, reusable playbooks +**Cons**: Requires Ansible installation + +## Example Configurations + +### Example 1: Simple DHCP Setup + +```yaml +proxmox: + host: "192.168.1.100" + node: "pve" + auth_method: "password" + username: "root@pam" + password: "your-password" + +lxc: + vmid: 200 + hostname: "qr-generator" + template: "ubuntu-22.04-standard" + +network: + bridge: "vmbr0" + ip_method: "dhcp" + +automation: + tool: "shell" +``` + +### Example 2: Production Setup with Static IP + +```yaml +proxmox: + host: "192.168.1.100" + node: "pve" + auth_method: "api_token" + api_token_id: "root@pam!deploy" + api_token_secret: "xxxx-xxxx-xxxx" + +lxc: + vmid: 200 + hostname: "qr-generator" + template: "ubuntu-22.04-standard" + unprivileged: true + onboot: true + +resources: + memory: 2048 + cores: 2 + disk_size: "10G" + +network: + bridge: "vmbr0" + ip_method: "static" + ip_address: "192.168.1.150/24" + gateway: "192.168.1.1" + nameserver: "8.8.8.8" + +reverse_proxy: + enabled: true + domain: "qr.example.com" + ssl_enabled: true + ssl_method: "letsencrypt" + letsencrypt_email: "admin@example.com" + +security: + ssh_public_key: "ssh-rsa AAAAB3NzaC1yc2E..." + configure_firewall: true + allowed_ips: "192.168.1.0/24" + +automation: + tool: "shell" +``` + +## Troubleshooting + +### Can't connect to Proxmox API + +```bash +# Test API connection +curl -k https://YOUR_PROXMOX_IP:8006/api2/json +``` + +### Container creation fails + +- Check VMID is not already in use: `pct list` +- Verify template exists: `pveam list local` +- Check storage has space: `pvesm status` + +### Network issues + +```bash +# Inside container, check network +ip addr show +ip route +ping 8.8.8.8 +``` + +### Application won't start + +```bash +# SSH into container +ssh root@CONTAINER_IP + +# Check service status +systemctl status qr-generator + +# Check logs +journalctl -u qr-generator -f +``` + +## Post-Deployment + +### Access the Application + +- **With DHCP**: + 1. Find IP: `pct exec VMID ip addr show eth0` + 2. Access: `http://CONTAINER_IP:8501` + +- **With Static IP**: + - Access: `http://YOUR_STATIC_IP:8501` + +- **With Reverse Proxy**: + - Access: `https://your-domain.com` + +### Manage the Container + +```bash +# Start container +pct start VMID + +# Stop container +pct stop VMID + +# Enter container console +pct enter VMID + +# Check container status +pct status VMID + +# View container config +pct config VMID +``` + +### Manage the Application + +```bash +# Inside container +systemctl status qr-generator # Check status +systemctl restart qr-generator # Restart app +systemctl stop qr-generator # Stop app +systemctl start qr-generator # Start app +journalctl -u qr-generator -f # View logs +``` + +## Next Steps + +1. Fill out the configuration file +2. Let me know when ready, and I'll generate the deployment scripts +3. Review and run the deployment +4. Access your QR code generator! + +## Support + +If you encounter any issues: +1. Check the logs (see Troubleshooting section) +2. Verify all configuration values are correct +3. Ensure Proxmox has necessary permissions and resources +4. Ask for help with specific error messages diff --git a/proxmox-deployment-config.yaml b/proxmox-deployment-config.yaml new file mode 100644 index 0000000..e6f5145 --- /dev/null +++ b/proxmox-deployment-config.yaml @@ -0,0 +1,204 @@ +# Proxmox LXC Deployment Configuration +# Fill out this configuration file to automate the deployment of QR Code Generator + +# ============================================================================== +# PROXMOX HOST CONFIGURATION +# ============================================================================== +proxmox: + # Proxmox host IP address or hostname + host: "" # Example: 192.168.1.100 + + # Proxmox API port (default: 8006) + port: 8006 + + # Authentication method: "api_token" or "password" + auth_method: "api_token" # Recommended: api_token + + # API Token (if using api_token auth) + # Format: USER@REALM!TOKENID=UUID + api_token_id: "" # Example: root@pam!terraform + api_token_secret: "" # Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + + # OR Username/Password (if using password auth) + username: "" # Example: root@pam + password: "" # Leave empty if using api_token + + # Node name where LXC should be created + node: "pve" # Default: pve + + # Deployment method: "local" (run from Proxmox host) or "remote" (run from this machine) + deployment_method: "local" # Options: local, remote + +# ============================================================================== +# LXC CONTAINER CONFIGURATION +# ============================================================================== +lxc: + # Container ID (must be unique, typically 100-999) + vmid: 200 # Change this to an available ID + + # Container hostname + hostname: "qr-generator" + + # Linux distribution template + # Run 'pveam available' on Proxmox to see available templates + template: "ubuntu-22.04-standard" # Options: ubuntu-22.04-standard, debian-12-standard, alpine-3.18-default + + # Storage pool for container template + template_storage: "local" # Where templates are stored + + # Storage pool for container rootfs + rootfs_storage: "local-lvm" # Options: local-lvm, local-zfs, etc. + + # Container type + unprivileged: true # true = more secure (recommended), false = privileged + + # Auto-start container on Proxmox boot + onboot: true # true or false + + # Start container after creation + start_after_creation: true # true or false + +# ============================================================================== +# RESOURCE ALLOCATION +# ============================================================================== +resources: + # RAM in MB + memory: 2048 # Recommended: 1024-2048 MB + + # Swap in MB + swap: 512 # Recommended: 512 MB + + # Number of CPU cores + cores: 2 # Recommended: 1-2 cores + + # CPU limit (percentage, 0-100) + cpulimit: 0 # 0 = unlimited + + # Disk size + disk_size: "10G" # Example: 8G, 10G, 20G + +# ============================================================================== +# NETWORK CONFIGURATION +# ============================================================================== +network: + # Network bridge + bridge: "vmbr0" # Default: vmbr0 + + # IP configuration method: "dhcp" or "static" + ip_method: "dhcp" # Options: dhcp, static + + # Static IP configuration (only if ip_method is "static") + ip_address: "" # Example: 192.168.1.150/24 + gateway: "" # Example: 192.168.1.1 + nameserver: "" # Example: 8.8.8.8 or 192.168.1.1 + + # VLAN tag (optional, leave empty for no VLAN) + vlan_tag: "" # Example: 10 + + # Firewall enabled + firewall: false # true or false + +# ============================================================================== +# APPLICATION CONFIGURATION +# ============================================================================== +application: + # Port for Streamlit application + port: 8501 # Default: 8501 + + # Application directory inside container + app_dir: "/opt/qr-code-generator" + + # Python version + python_version: "3.11" # Options: 3.11, 3.10, 3.9 + + # Git repository URL (leave empty to copy files directly) + git_repo: "" # Example: https://github.com/yourusername/qr-code-generator.git + git_branch: "main" # Default: main + + # Service management + systemd_service: true # Create systemd service to manage the app + restart_on_failure: true # Auto-restart service on failure + +# ============================================================================== +# REVERSE PROXY & SSL (OPTIONAL) +# ============================================================================== +reverse_proxy: + # Enable reverse proxy (nginx) + enabled: false # true or false + + # Domain name for the application + domain: "" # Example: qr.example.com + + # Enable SSL/HTTPS + ssl_enabled: false # true or false + + # SSL certificate method: "letsencrypt" or "self-signed" + ssl_method: "letsencrypt" # Options: letsencrypt, self-signed + + # Let's Encrypt email (required if ssl_method is letsencrypt) + letsencrypt_email: "" # Example: admin@example.com + + # HTTP to HTTPS redirect + force_https: true # true or false + +# ============================================================================== +# SECURITY & ACCESS +# ============================================================================== +security: + # SSH key for root access (recommended) + ssh_public_key: "" # Example: ssh-rsa AAAAB3NzaC1yc2E... user@host + + # Allow SSH root login + permit_root_login: true # true or false + + # Root password (leave empty to keep default or use SSH key only) + root_password: "" # Leave empty for SSH key auth only + + # Configure firewall rules + configure_firewall: false # true or false + + # Allowed IP addresses/ranges for access (comma-separated) + allowed_ips: "" # Example: 192.168.1.0/24,10.0.0.0/8 or leave empty for all + +# ============================================================================== +# UPDATES & MAINTENANCE +# ============================================================================== +maintenance: + # Enable automatic security updates + auto_security_updates: true # true or false + + # Install additional monitoring tools + monitoring_tools: false # true or false (installs htop, ncdu, etc.) + + # Timezone + timezone: "UTC" # Example: America/New_York, Europe/London, UTC + +# ============================================================================== +# DEPLOYMENT AUTOMATION PREFERENCES +# ============================================================================== +automation: + # Deployment tool preference + # Options: "shell" (simple bash scripts), "terraform" (IaC), "ansible" (config management) + tool: "shell" + + # Backup configuration before deployment + backup_enabled: false # true or false + + # Validate configuration before deployment + validate_before_deploy: true # true or false + + # Verbose output during deployment + verbose: true # true or false + +# ============================================================================== +# NOTES +# ============================================================================== +# Additional notes or requirements: +notes: | + Add any additional notes, requirements, or customizations here. + + Examples: + - Need to access from specific VPN + - Custom DNS requirements + - Integration with other services + - Backup requirements