michael/qr-code-generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

proxmox deployement

Browse Source
This commit is contained in:
Michael Schapira
2025-11-12 22:12:47 -05:00
parent 540735cc1a
commit 7290304d5f
2 changed files with 536 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

332
PROXMOX-DEPLOYMENT.md Normal file
View File

@@ -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

204
proxmox-deployment-config.yaml Normal file
View File

@@ -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