qr-code-generator/PROXMOX-DEPLOYMENT.md

# 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