michael/qr-code-generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7290304d5fe56e16f2f09ec1b1d67a89848f16bf
qr-code-generator/PROXMOX-DEPLOYMENT.md

7.1 KiB
Raw Blame History

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:

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:

# 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:

# 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

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

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

# 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

# Inside container, check network
ip addr show
ip route
ping 8.8.8.8

Application won't start

# 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

# 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

# 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
Reference in New Issue View Git Blame Copy Permalink