mirror of
https://github.com/Grace-Solutions/Depl0y-Custom.git
synced 2026-07-26 11:28:19 +00:00
Initial Commit
This commit is contained in:
Alphaeus Mote
@@ -0,0 +1,705 @@
|
||||
# Cloud Images - Complete Guide
|
||||
|
||||
## Table of Contents
|
||||
1. [What Are Cloud Images?](#what-are-cloud-images)
|
||||
2. [Why Use Cloud Images?](#why-use-cloud-images)
|
||||
3. [One-Time Setup](#one-time-setup)
|
||||
4. [How to Use Cloud Images](#how-to-use-cloud-images)
|
||||
5. [Available Cloud Images](#available-cloud-images)
|
||||
6. [How It Works (Technical)](#how-it-works-technical)
|
||||
7. [Troubleshooting](#troubleshooting)
|
||||
8. [FAQ](#faq)
|
||||
|
||||
---
|
||||
|
||||
## What Are Cloud Images?
|
||||
|
||||
Cloud images are pre-configured, ready-to-deploy operating system disk images. Instead of manually installing an OS (which takes 15-20 minutes), cloud images allow you to:
|
||||
|
||||
- **Deploy VMs in 30 seconds** (after initial template creation)
|
||||
- **Automatically configure credentials** (username/password)
|
||||
- **Auto-configure networking** (DHCP or static IP)
|
||||
- **Skip manual OS installation** completely
|
||||
|
||||
Think of it like cloning a pre-installed OS with your custom settings applied automatically.
|
||||
|
||||
---
|
||||
|
||||
## Why Use Cloud Images?
|
||||
|
||||
### Traditional ISO Installation:
|
||||
- Upload ISO file (~1GB download)
|
||||
- Create VM
|
||||
- Boot from ISO
|
||||
- Click through installation wizard
|
||||
- Wait 15-20 minutes
|
||||
- **Total time: 20-30 minutes per VM**
|
||||
|
||||
### Cloud Image Installation:
|
||||
- Select cloud image
|
||||
- Configure CPU, RAM, disk, credentials
|
||||
- Click "Create VM"
|
||||
- **First time: 5-10 minutes** (creates reusable template)
|
||||
- **Every time after: 30 seconds** ⚡
|
||||
|
||||
**100x faster after the first deployment!**
|
||||
|
||||
---
|
||||
|
||||
## One-Time Setup
|
||||
|
||||
Cloud images require SSH access to your Proxmox server for initial template creation. This is a **ONE-TIME** setup that takes about 1 minute.
|
||||
|
||||
### Step 1: Check if Setup is Needed
|
||||
|
||||
Open Depl0y web UI and go to **Settings** page. Look for the "Cloud Image Setup" section:
|
||||
|
||||
- **Green box (✅)**: Setup already complete! You're good to go.
|
||||
- **Yellow box (⚠️)**: Setup required. Continue to Step 2.
|
||||
|
||||
### Step 2: Run the Setup Script
|
||||
|
||||
The setup script is already on your Depl0y server at `/tmp/enable_cloud_images.sh`.
|
||||
|
||||
**⚠️ IMPORTANT: Run this script ON YOUR DEPL0Y SERVER (not on Proxmox!)**
|
||||
|
||||
The script is located on your Depl0y server at `/tmp/enable_cloud_images.sh`. It will automatically connect to Proxmox to set up SSH access.
|
||||
|
||||
**Method 1: Copy from Web UI (Recommended)**
|
||||
|
||||
1. In the Settings page, click the **"Copy"** button next to the setup command
|
||||
2. SSH into your **Depl0y server** (the server where Depl0y is installed):
|
||||
```bash
|
||||
ssh administrator@your-depl0y-server
|
||||
# Or: ssh administrator@deploy
|
||||
```
|
||||
3. Paste and run the command:
|
||||
```bash
|
||||
sudo /tmp/enable_cloud_images.sh
|
||||
```
|
||||
|
||||
**Method 2: Manual Command**
|
||||
|
||||
If you're already logged into your Depl0y server, just run:
|
||||
```bash
|
||||
sudo /tmp/enable_cloud_images.sh
|
||||
```
|
||||
|
||||
**What Happens:**
|
||||
1. Script runs **on Depl0y server** (where you run the command)
|
||||
2. Generates SSH keys **on Depl0y server**
|
||||
3. Prompts you for **Proxmox root password**
|
||||
4. Uses SSH to copy the key **from Depl0y to Proxmox**
|
||||
5. Verifies connection works
|
||||
|
||||
### Step 3: Enter Proxmox Password
|
||||
|
||||
The script will prompt you:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Please enter the ROOT PASSWORD for Proxmox server: pve.agit8or.net
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Password:
|
||||
```
|
||||
|
||||
**Enter your Proxmox root password** (the password will not be displayed as you type for security).
|
||||
|
||||
### Step 4: Wait for Completion
|
||||
|
||||
The script will:
|
||||
1. ✓ Check if `sshpass` is installed (installs if needed)
|
||||
2. ✓ Generate SSH key pair (if not exists)
|
||||
3. ✓ Copy SSH public key to Proxmox
|
||||
4. ✓ Verify SSH connection works
|
||||
|
||||
You'll see:
|
||||
```
|
||||
╔════════════════════════════════════════════════════════════╗
|
||||
║ ✅ SUCCESS! ║
|
||||
╚════════════════════════════════════════════════════════════╝
|
||||
|
||||
Cloud images are now fully configured!
|
||||
|
||||
🎉 What happens now:
|
||||
• Go to the web UI and create a VM
|
||||
• Select any cloud image (Ubuntu, Debian, etc.)
|
||||
• Click 'Create VM'
|
||||
• The system will automatically:
|
||||
- Download the cloud image to Proxmox (first time only)
|
||||
- Create a bootable template (first time only)
|
||||
- Clone and deploy your VM with your credentials
|
||||
- Start the VM ready to use!
|
||||
|
||||
First deployment per cloud image: ~5-10 minutes
|
||||
All subsequent deployments: ~30 seconds
|
||||
|
||||
✨ Everything is automatic from now on!
|
||||
```
|
||||
|
||||
### Step 5: Verify in Web UI
|
||||
|
||||
1. Go back to **Settings** page in Depl0y web UI
|
||||
2. Click **"Re-check Status"** button
|
||||
3. You should see a **green success box**: "Cloud Images Enabled! ✅"
|
||||
|
||||
**Setup is complete!** You never have to do this again.
|
||||
|
||||
---
|
||||
|
||||
## How to Use Cloud Images
|
||||
|
||||
### Creating Your First Cloud Image VM
|
||||
|
||||
1. **Go to Create VM Page**
|
||||
- Click "Create VM" in the navigation menu
|
||||
|
||||
2. **Basic Configuration**
|
||||
- **Name**: Enter a name for your VM (e.g., "ubuntu-web-01")
|
||||
- **Datacenter**: Select your Proxmox datacenter
|
||||
- **Node**: Select which Proxmox node to deploy on
|
||||
|
||||
3. **Installation Method**
|
||||
- Select **"Cloud Image (Fast)"**
|
||||
- Choose a cloud image from the dropdown:
|
||||
- Ubuntu 24.04 LTS
|
||||
- Ubuntu 22.04 LTS
|
||||
- Ubuntu 20.04 LTS
|
||||
- Debian 12
|
||||
- Debian 11
|
||||
|
||||
4. **Resources**
|
||||
- **CPU Cores**: 2 (or more)
|
||||
- **Memory (RAM)**: 2048 MB (or more)
|
||||
- **Disk Size**: 20 GB (or more)
|
||||
|
||||
5. **Storage & Network**
|
||||
- **Storage Pool**: Select where to store the VM disk
|
||||
- **Network Bridge**: Select network (usually vmbr0)
|
||||
|
||||
6. **Cloud-Init Configuration**
|
||||
- **Username**: Your desired username (e.g., "admin", "ubuntu")
|
||||
- **Password**: Your desired password
|
||||
- **SSH Public Key** (optional): Paste your SSH public key for key-based auth
|
||||
- **IP Configuration**: Choose DHCP or Static IP
|
||||
|
||||
7. **Advanced Options** (optional)
|
||||
- CPU Type
|
||||
- BIOS (SeaBIOS or UEFI)
|
||||
- VGA Type
|
||||
- Boot Order
|
||||
|
||||
8. **Click "Create VM"**
|
||||
|
||||
### What Happens Next?
|
||||
|
||||
**First Time Using This Cloud Image:**
|
||||
- Status: "Setting up cloud image (first time - takes ~5 min)..."
|
||||
- The system automatically:
|
||||
1. Downloads the cloud image to Depl0y server (~300-700 MB)
|
||||
2. Uploads it to Proxmox via SSH
|
||||
3. Creates a VM template on Proxmox
|
||||
4. Clones the template to create your VM
|
||||
5. Configures cloud-init with your credentials
|
||||
6. Starts the VM
|
||||
|
||||
**Time: 5-10 minutes** ⏱️
|
||||
|
||||
**Every Time After (Same Cloud Image):**
|
||||
- Status: "Cloning template..."
|
||||
- The system automatically:
|
||||
1. Clones existing template (instant!)
|
||||
2. Configures cloud-init with your credentials
|
||||
3. Starts the VM
|
||||
|
||||
**Time: 30 seconds** ⚡
|
||||
|
||||
### Accessing Your VM
|
||||
|
||||
Once the VM is created and started:
|
||||
|
||||
**SSH Access:**
|
||||
```bash
|
||||
ssh username@vm-ip-address
|
||||
```
|
||||
|
||||
**Console Access:**
|
||||
- Click on the VM in Depl0y
|
||||
- Click "Console" button
|
||||
- Login with your configured username/password
|
||||
|
||||
---
|
||||
|
||||
## Available Cloud Images
|
||||
|
||||
### Ubuntu
|
||||
|
||||
| Image | Version | Use Case | LTS Until |
|
||||
|-------|---------|----------|-----------|
|
||||
| Ubuntu 24.04 LTS | Noble Numbat | Latest features | April 2029 |
|
||||
| Ubuntu 22.04 LTS | Jammy Jellyfish | Stable production | April 2027 |
|
||||
| Ubuntu 20.04 LTS | Focal Fossa | Legacy apps | April 2025 |
|
||||
|
||||
### Debian
|
||||
|
||||
| Image | Version | Use Case |
|
||||
|-------|---------|----------|
|
||||
| Debian 12 | Bookworm | Latest stable |
|
||||
| Debian 11 | Bullseye | Previous stable |
|
||||
|
||||
**More cloud images can be added!** Contact your administrator or submit a feature request.
|
||||
|
||||
---
|
||||
|
||||
## How It Works (Technical)
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Depl0y Server │
|
||||
│ │
|
||||
│ 1. Downloads │──────┐
|
||||
│ cloud image │ │
|
||||
└─────────────────┘ │
|
||||
│ SCP Upload
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Proxmox Server │
|
||||
│ │
|
||||
│ 2. Import disk │
|
||||
│ 3. Convert to │
|
||||
│ template │
|
||||
│ │
|
||||
│ Template ID: │
|
||||
│ 9001, 9002... │
|
||||
└─────────────────┘
|
||||
│
|
||||
│ Clone via API
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ New VM │
|
||||
│ + Cloud-init │
|
||||
│ configured │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Template ID System
|
||||
|
||||
Cloud images are converted to Proxmox templates with predictable IDs:
|
||||
|
||||
- Template ID = `9000 + cloud_image_id`
|
||||
- Ubuntu 24.04 (id=1) → Template 9001
|
||||
- Ubuntu 22.04 (id=2) → Template 9002
|
||||
- Debian 12 (id=3) → Template 9003
|
||||
- etc.
|
||||
|
||||
### Template Creation Process
|
||||
|
||||
**First VM deployment from a cloud image:**
|
||||
|
||||
1. **Download** (Depl0y server):
|
||||
```bash
|
||||
wget https://cloud-images.ubuntu.com/.../ubuntu-24.04-server-cloudimg-amd64.img
|
||||
# Stored in: /var/lib/depl0y/cloud-images/
|
||||
```
|
||||
|
||||
2. **Upload to Proxmox** (via SSH):
|
||||
```bash
|
||||
scp ubuntu-24.04-server-cloudimg-amd64.img root@pve.agit8or.net:/tmp/
|
||||
```
|
||||
|
||||
3. **Create Template VM** (via SSH on Proxmox):
|
||||
```bash
|
||||
# Create empty VM
|
||||
qm create 9001 --name Ubuntu-24.04-LTS --memory 2048 --cores 2 \
|
||||
--net0 virtio,bridge=vmbr0 --ostype l26 --scsihw virtio-scsi-pci
|
||||
|
||||
# Import cloud image as disk
|
||||
qm importdisk 9001 /tmp/ubuntu-24.04-server-cloudimg-amd64.img local-lvm --format qcow2
|
||||
|
||||
# Configure disk and boot
|
||||
qm set 9001 --scsi0 local-lvm:vm-9001-disk-0
|
||||
qm set 9001 --boot order=scsi0
|
||||
|
||||
# Add cloud-init drive
|
||||
qm set 9001 --ide2 local-lvm:cloudinit
|
||||
|
||||
# Convert to template
|
||||
qm template 9001
|
||||
```
|
||||
|
||||
4. **Clone Template** (via Proxmox API):
|
||||
```python
|
||||
proxmox.nodes(node).qemu(9001).clone.post(
|
||||
newid=vm_id,
|
||||
name=vm_name,
|
||||
full=1, # Full clone
|
||||
storage=storage
|
||||
)
|
||||
```
|
||||
|
||||
5. **Configure Cloud-init** (via Proxmox API):
|
||||
```python
|
||||
proxmox.nodes(node).qemu(vm_id).config.set(
|
||||
ciuser=username,
|
||||
cipassword=password,
|
||||
ipconfig0=network_config,
|
||||
sshkeys=ssh_public_key
|
||||
)
|
||||
```
|
||||
|
||||
### Subsequent Deployments
|
||||
|
||||
**All VMs after the first:**
|
||||
- **Skip steps 1-3** (template already exists!)
|
||||
- **Only run steps 4-5** (clone + configure)
|
||||
- **Result**: 30-second deployments
|
||||
|
||||
### Why SSH is Required
|
||||
|
||||
The `qm importdisk` command does not have a Proxmox API endpoint. It can only be executed via SSH on the Proxmox server. This is why SSH setup is required for the **first** deployment of each cloud image type.
|
||||
|
||||
**After template creation:**
|
||||
- All operations use pure Proxmox API
|
||||
- No SSH required for VM cloning
|
||||
- Fast and efficient deployments
|
||||
|
||||
### Security
|
||||
|
||||
- **SSH Key Authentication**: Password-free after setup
|
||||
- **Public Key Only**: Only public key stored on Proxmox
|
||||
- **No Password Storage**: Proxmox password never stored in database
|
||||
- **Template Isolation**: Templates separate from user VMs
|
||||
- **Cloud-init Encryption**: Credentials encrypted in transit
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "SSH access not configured"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
Error: SSH access not configured. Please run this ONE-TIME setup command:
|
||||
|
||||
sudo /tmp/enable_cloud_images.sh
|
||||
|
||||
After that, cloud images will deploy automatically!
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
1. SSH to your Depl0y server
|
||||
2. Run: `sudo /tmp/enable_cloud_images.sh`
|
||||
3. Enter your Proxmox root password when prompted
|
||||
4. Wait for "✅ SUCCESS!" message
|
||||
5. Try creating the VM again
|
||||
|
||||
### SSH Setup Script Fails
|
||||
|
||||
**Error: "Permission denied (publickey,password)"**
|
||||
|
||||
**Possible Causes:**
|
||||
- Wrong Proxmox password
|
||||
- SSH password authentication disabled on Proxmox
|
||||
|
||||
**Solution 1: Verify Password**
|
||||
```bash
|
||||
# Test SSH with password manually
|
||||
ssh root@pve.agit8or.net
|
||||
# If this fails with your password, reset Proxmox root password
|
||||
```
|
||||
|
||||
**Solution 2: Enable Password Auth (if disabled)**
|
||||
|
||||
On your Proxmox server, edit SSH config:
|
||||
```bash
|
||||
sudo nano /etc/ssh/sshd_config
|
||||
```
|
||||
|
||||
Find and change:
|
||||
```
|
||||
PasswordAuthentication yes
|
||||
```
|
||||
|
||||
Restart SSH:
|
||||
```bash
|
||||
sudo systemctl restart sshd
|
||||
```
|
||||
|
||||
Then run the setup script again.
|
||||
|
||||
**Solution 3: Manual SSH Key Setup**
|
||||
|
||||
If the automated script fails, set up SSH manually:
|
||||
|
||||
1. On Depl0y server:
|
||||
```bash
|
||||
sudo -u depl0y ssh-keygen -t rsa -b 4096 -f /opt/depl0y/.ssh/id_rsa -N ""
|
||||
sudo -u depl0y cat /opt/depl0y/.ssh/id_rsa.pub
|
||||
```
|
||||
|
||||
2. Copy the public key output
|
||||
|
||||
3. On Proxmox server:
|
||||
```bash
|
||||
mkdir -p ~/.ssh
|
||||
chmod 700 ~/.ssh
|
||||
nano ~/.ssh/authorized_keys
|
||||
# Paste the public key, save and exit
|
||||
chmod 600 ~/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
4. Test from Depl0y server:
|
||||
```bash
|
||||
sudo -u depl0y ssh root@pve.agit8or.net "echo test"
|
||||
```
|
||||
|
||||
### VM Created But Won't Boot
|
||||
|
||||
**Symptoms:**
|
||||
- VM starts but no OS loads
|
||||
- Black screen or BIOS errors
|
||||
- "No bootable device" error
|
||||
|
||||
**Cause:**
|
||||
Template doesn't exist or is corrupt.
|
||||
|
||||
**Solution:**
|
||||
Delete the template and let it recreate:
|
||||
|
||||
1. Check which template exists:
|
||||
```bash
|
||||
ssh root@pve.agit8or.net "qm list | grep 900"
|
||||
```
|
||||
|
||||
2. Delete the problematic template:
|
||||
```bash
|
||||
# For Ubuntu 24.04 (template 9001)
|
||||
ssh root@pve.agit8or.net "qm destroy 9001"
|
||||
```
|
||||
|
||||
3. Try creating the VM again - template will be recreated automatically
|
||||
|
||||
### Cloud-init Not Working
|
||||
|
||||
**Symptoms:**
|
||||
- Can't login with configured credentials
|
||||
- Default username/password required
|
||||
- Network not configured
|
||||
|
||||
**Cause:**
|
||||
Cloud-init configuration failed or not applied.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check cloud-init logs on the VM:
|
||||
```bash
|
||||
# Login via console with default credentials
|
||||
sudo cat /var/log/cloud-init.log
|
||||
sudo cat /var/log/cloud-init-output.log
|
||||
```
|
||||
|
||||
2. Verify cloud-init config in Proxmox:
|
||||
```bash
|
||||
ssh root@pve.agit8or.net "qm cloudinit dump <vmid> user"
|
||||
```
|
||||
|
||||
3. Manually set cloud-init (if needed):
|
||||
```bash
|
||||
# Via Proxmox UI:
|
||||
# VM → Cloud-Init → Edit settings
|
||||
```
|
||||
|
||||
### Template Creation Stuck
|
||||
|
||||
**Symptoms:**
|
||||
- Status shows "Setting up cloud image..." for 20+ minutes
|
||||
- No progress
|
||||
|
||||
**Cause:**
|
||||
- Network issue downloading cloud image
|
||||
- Proxmox storage full
|
||||
- SSH connection lost
|
||||
|
||||
**Check Logs:**
|
||||
```bash
|
||||
sudo journalctl -u depl0y-backend -f --no-pager
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check download progress:**
|
||||
```bash
|
||||
ls -lh /var/lib/depl0y/cloud-images/
|
||||
# If file is growing, download is in progress
|
||||
```
|
||||
|
||||
2. **Check Proxmox storage:**
|
||||
```bash
|
||||
ssh root@pve.agit8or.net "df -h"
|
||||
# Ensure storage has 5+ GB free
|
||||
```
|
||||
|
||||
3. **Check SSH connection:**
|
||||
```bash
|
||||
sudo -u depl0y ssh root@pve.agit8or.net "echo test"
|
||||
```
|
||||
|
||||
4. **Restart the deployment:**
|
||||
- Delete the partially created template
|
||||
- Try creating the VM again
|
||||
|
||||
### Check Templates on Proxmox
|
||||
|
||||
List all templates:
|
||||
```bash
|
||||
ssh root@pve.agit8or.net "qm list | grep 900"
|
||||
```
|
||||
|
||||
Example output:
|
||||
```
|
||||
9001 Ubuntu-24.04-LTS 0 2048 0.00 0
|
||||
9002 Ubuntu-22.04-LTS 0 2048 0.00 0
|
||||
```
|
||||
|
||||
Delete a template:
|
||||
```bash
|
||||
ssh root@pve.agit8or.net "qm destroy 9001"
|
||||
```
|
||||
|
||||
### Verify SSH Status from Command Line
|
||||
|
||||
**Test SSH access:**
|
||||
```bash
|
||||
sudo -u depl0y ssh -o BatchMode=yes -o ConnectTimeout=5 \
|
||||
-o StrictHostKeyChecking=no root@pve.agit8or.net "echo test"
|
||||
```
|
||||
|
||||
**If successful, you'll see:**
|
||||
```
|
||||
test
|
||||
```
|
||||
|
||||
**If not configured:**
|
||||
```
|
||||
Permission denied (publickey,password).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: Do I need to run the setup script for every VM?
|
||||
**A:** No! The setup script is run **once** per Depl0y installation. After that, all cloud image deployments are automatic.
|
||||
|
||||
### Q: Do I need to run the setup script for each cloud image?
|
||||
**A:** No! One setup enables **all** cloud images. The first deployment of each cloud image type takes 5-10 minutes to create the template, then all subsequent deployments are 30 seconds.
|
||||
|
||||
### Q: What if I add a new Proxmox node?
|
||||
**A:** The SSH key is configured per Proxmox host, not per node. If you add a node to an existing cluster, no new setup is needed. If you add a completely new Proxmox host/cluster, you'll need to run the setup script once for that new host.
|
||||
|
||||
### Q: Can I use cloud images and ISO images?
|
||||
**A:** Yes! Both installation methods work side-by-side. Use cloud images for quick deployments, ISOs for custom installations or distros without cloud images.
|
||||
|
||||
### Q: Where are cloud images stored?
|
||||
**A:**
|
||||
- **Depl0y server**: `/var/lib/depl0y/cloud-images/` (original downloads)
|
||||
- **Proxmox server**: Imported as disks in configured storage (e.g., local-lvm)
|
||||
|
||||
### Q: How much disk space do cloud images use?
|
||||
**A:**
|
||||
- **Download**: 300-700 MB per cloud image
|
||||
- **Template on Proxmox**: 2-3 GB per template
|
||||
- **Cloned VMs**: Your configured disk size (20+ GB recommended)
|
||||
|
||||
### Q: Can I customize the cloud images?
|
||||
**A:** Cloud images are standard upstream images from Ubuntu/Debian. You can:
|
||||
- Customize credentials (via cloud-init)
|
||||
- Customize network (via cloud-init)
|
||||
- Add SSH keys (via cloud-init)
|
||||
- Install software after deployment (via Ansible, scripts, etc.)
|
||||
|
||||
If you need pre-customized images, consider using Packer to build custom images.
|
||||
|
||||
### Q: What happens if template creation fails?
|
||||
**A:** The deployment will fail with an error message. Check the logs, fix the issue (usually SSH or storage), and try again. The system will automatically retry template creation.
|
||||
|
||||
### Q: Can I delete templates?
|
||||
**A:** Yes, but if you delete a template, the next VM deployment for that cloud image will take 5-10 minutes to recreate the template. Templates are safe to delete if you need to free space.
|
||||
|
||||
### Q: How do I add more cloud images?
|
||||
**A:** Cloud images are defined in the database. You can:
|
||||
1. Contact your Depl0y administrator
|
||||
2. Submit a feature request
|
||||
3. Manually add via database (advanced users)
|
||||
|
||||
### Q: Does cloud-init work on all images?
|
||||
**A:** Yes! All official Ubuntu and Debian cloud images have cloud-init pre-installed and configured. That's what makes them "cloud images."
|
||||
|
||||
### Q: Can I use Windows cloud images?
|
||||
**A:** Windows doesn't have official cloud images like Linux. For Windows VMs, use the traditional ISO installation method. You can create custom Windows templates manually in Proxmox.
|
||||
|
||||
### Q: What if I don't want to give Proxmox root SSH access?
|
||||
**A:** SSH root access is required for the `qm importdisk` command during template creation. This is a Proxmox limitation. For security:
|
||||
- SSH uses key-based auth (no password storage)
|
||||
- SSH only used during template creation
|
||||
- All subsequent operations use Proxmox API
|
||||
- You can disable SSH after all templates are created (though you'll need to re-enable for new cloud image types)
|
||||
|
||||
### Q: How do I know which template ID corresponds to which cloud image?
|
||||
**A:** Template ID = 9000 + cloud_image_id. You can check cloud image IDs in the database or via the API. Common mappings:
|
||||
- 9001: Ubuntu 24.04 LTS
|
||||
- 9002: Ubuntu 22.04 LTS
|
||||
- 9003: Ubuntu 20.04 LTS
|
||||
- 9004: Debian 12
|
||||
- 9005: Debian 11
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Check System Logs
|
||||
```bash
|
||||
# Backend logs
|
||||
sudo journalctl -u depl0y-backend -f --no-pager
|
||||
|
||||
# Last 50 lines
|
||||
sudo journalctl -u depl0y-backend -n 50 --no-pager
|
||||
```
|
||||
|
||||
### Test SSH Manually
|
||||
```bash
|
||||
# As depl0y user
|
||||
sudo -u depl0y ssh root@pve.agit8or.net "qm list"
|
||||
|
||||
# Check SSH key
|
||||
sudo -u depl0y cat /opt/depl0y/.ssh/id_rsa.pub
|
||||
```
|
||||
|
||||
### View Cloud Images in Database
|
||||
```bash
|
||||
sudo -u depl0y sqlite3 /var/lib/depl0y/db/depl0y.db "SELECT id, name, filename, is_downloaded FROM cloud_images WHERE is_available=1;"
|
||||
```
|
||||
|
||||
### File Locations
|
||||
- **Setup script**: `/tmp/enable_cloud_images.sh`
|
||||
- **Cloud image downloads**: `/var/lib/depl0y/cloud-images/`
|
||||
- **SSH keys**: `/opt/depl0y/.ssh/`
|
||||
- **Backend code**: `/opt/depl0y/backend/app/services/deployment.py`
|
||||
- **Database**: `/var/lib/depl0y/db/depl0y.db`
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter issues not covered in this guide:
|
||||
|
||||
1. **Check logs**: `sudo journalctl -u depl0y-backend -f`
|
||||
2. **Verify SSH**: `sudo -u depl0y ssh root@pve.agit8or.net "echo test"`
|
||||
3. **Check templates**: `ssh root@pve.agit8or.net "qm list | grep 900"`
|
||||
4. **Contact support** or submit a bug report via the web UI
|
||||
|
||||
---
|
||||
|
||||
**Happy deploying!** 🚀
|
||||
@@ -0,0 +1,139 @@
|
||||
# Cloud Images - Quick Start Guide
|
||||
|
||||
## What Are Cloud Images?
|
||||
|
||||
Cloud images let you deploy VMs in **30 seconds** instead of 20 minutes. No manual OS installation needed!
|
||||
|
||||
---
|
||||
|
||||
## One-Time Setup (Takes 1 Minute)
|
||||
|
||||
### Step 1: Check Status in Web UI
|
||||
|
||||
Go to **Settings** → Look for **"Cloud Image Setup"** section
|
||||
|
||||
- **Green box (✅)**: Already configured! Skip to "Using Cloud Images" below.
|
||||
- **Yellow box (⚠️)**: Setup needed. Continue to Step 2.
|
||||
|
||||
### Step 2: Run Setup Script
|
||||
|
||||
**IMPORTANT:** Run this script **ON YOUR DEPL0Y SERVER** (not on Proxmox!)
|
||||
|
||||
**Option A: Copy from Web UI**
|
||||
1. Click the **"Copy"** button in Settings page
|
||||
2. SSH to your **Depl0y server** (hostname: `deploy`)
|
||||
3. Paste and run the command
|
||||
|
||||
**Option B: Manual Command**
|
||||
|
||||
SSH to your **Depl0y server** and run:
|
||||
|
||||
```bash
|
||||
sudo /tmp/enable_cloud_images.sh
|
||||
```
|
||||
|
||||
**If you're already logged into the Depl0y server:**
|
||||
Just run the command directly - no need to SSH anywhere!
|
||||
|
||||
### Step 3: Enter Password
|
||||
|
||||
When prompted, enter your **Proxmox root password**:
|
||||
|
||||
```
|
||||
Password: [your-proxmox-root-password]
|
||||
```
|
||||
|
||||
(Password won't be displayed as you type - this is normal)
|
||||
|
||||
### Step 4: Done!
|
||||
|
||||
You'll see:
|
||||
|
||||
```
|
||||
✅ SUCCESS!
|
||||
|
||||
Cloud images are now fully configured!
|
||||
```
|
||||
|
||||
Go back to **Settings** in web UI and click **"Re-check Status"** to verify.
|
||||
|
||||
---
|
||||
|
||||
## Using Cloud Images
|
||||
|
||||
### Create a VM:
|
||||
|
||||
1. Go to **"Create VM"** in web UI
|
||||
2. Select **"Cloud Image (Fast)"** installation method
|
||||
3. Choose a cloud image:
|
||||
- Ubuntu 24.04 LTS
|
||||
- Ubuntu 22.04 LTS
|
||||
- Ubuntu 20.04 LTS
|
||||
- Debian 12
|
||||
- Debian 11
|
||||
4. Configure CPU, RAM, disk size
|
||||
5. Enter your desired **username** and **password**
|
||||
6. Click **"Create VM"**
|
||||
|
||||
### Deployment Times:
|
||||
|
||||
- **First time using a cloud image**: 5-10 minutes (creates template)
|
||||
- **Every time after that**: 30 seconds ⚡
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "SSH access not configured"
|
||||
|
||||
**Fix:** Run the setup script again:
|
||||
```bash
|
||||
sudo /tmp/enable_cloud_images.sh
|
||||
```
|
||||
|
||||
### Setup script fails with "Permission denied"
|
||||
|
||||
**Possible causes:**
|
||||
- Wrong password
|
||||
- SSH password auth disabled on Proxmox
|
||||
|
||||
**Fix:** Try password again, or manually enable SSH password authentication on Proxmox.
|
||||
|
||||
### VM boots but no OS
|
||||
|
||||
**Cause:** Template is missing or corrupt
|
||||
|
||||
**Fix:** Delete and recreate template:
|
||||
```bash
|
||||
ssh root@pve.agit8or.net "qm destroy 9001"
|
||||
```
|
||||
Then create a new VM - template will be recreated.
|
||||
|
||||
### Can't login to VM
|
||||
|
||||
**Cause:** Cloud-init didn't configure credentials
|
||||
|
||||
**Fix:** Check cloud-init logs via Proxmox console:
|
||||
```bash
|
||||
sudo cat /var/log/cloud-init.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Get Help
|
||||
|
||||
- **Full documentation**: `CLOUD_IMAGES_GUIDE.md`
|
||||
- **Check logs**: `sudo journalctl -u depl0y-backend -f`
|
||||
- **Verify SSH**: `sudo -u depl0y ssh root@pve.agit8or.net "echo test"`
|
||||
- **Check templates**: `ssh root@pve.agit8or.net "qm list | grep 900"`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
✅ **One-time setup**: 1 minute
|
||||
✅ **Maintenance**: Zero
|
||||
✅ **Deployment time**: 30 seconds
|
||||
✅ **Manual installation**: Never again
|
||||
|
||||
**Questions?** See full guide: `CLOUD_IMAGES_GUIDE.md`
|
||||
@@ -0,0 +1,132 @@
|
||||
# Contributing to Depl0y
|
||||
|
||||
Thank you for your interest in contributing to Depl0y! We welcome contributions from everyone.
|
||||
|
||||
## How Can I Contribute?
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
Before submitting a bug report:
|
||||
- Check the [existing issues](https://github.com/yourusername/depl0y/issues) to avoid duplicates
|
||||
- Gather information about the bug
|
||||
- Try to reproduce it with the latest version
|
||||
|
||||
When submitting a bug report, include:
|
||||
- Clear title and description
|
||||
- Steps to reproduce
|
||||
- Expected vs actual behavior
|
||||
- Screenshots if applicable
|
||||
- Environment details (OS, Docker version, etc.)
|
||||
- Relevant logs
|
||||
|
||||
### Suggesting Enhancements
|
||||
|
||||
Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:
|
||||
- Use a clear, descriptive title
|
||||
- Provide detailed description of the proposed feature
|
||||
- Explain why this enhancement would be useful
|
||||
- List any alternative solutions you've considered
|
||||
|
||||
### Pull Requests
|
||||
|
||||
1. **Fork the repository**
|
||||
2. **Create a branch** from `main`:
|
||||
```bash
|
||||
git checkout -b feature/my-feature
|
||||
```
|
||||
3. **Make your changes**
|
||||
4. **Test thoroughly**
|
||||
5. **Commit with clear messages**:
|
||||
```bash
|
||||
git commit -m "Add feature: description"
|
||||
```
|
||||
6. **Push to your fork**:
|
||||
```bash
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
7. **Open a Pull Request**
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Database
|
||||
|
||||
```bash
|
||||
docker-compose up -d db
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
### Python
|
||||
|
||||
- Follow PEP 8
|
||||
- Use type hints
|
||||
- Write docstrings for functions and classes
|
||||
- Maximum line length: 100 characters
|
||||
|
||||
### JavaScript/Vue
|
||||
|
||||
- Use ES6+ features
|
||||
- Follow Vue.js style guide
|
||||
- Use meaningful variable names
|
||||
- Add comments for complex logic
|
||||
|
||||
### Commits
|
||||
|
||||
- Use present tense ("Add feature" not "Added feature")
|
||||
- Reference issues and PRs when applicable
|
||||
- Keep commits focused and atomic
|
||||
|
||||
## Testing
|
||||
|
||||
### Backend Tests
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pytest
|
||||
```
|
||||
|
||||
### Frontend Tests
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run test
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- Update README.md if needed
|
||||
- Add docstrings to new functions
|
||||
- Update user guide for new features
|
||||
- Include inline comments for complex code
|
||||
|
||||
## Community
|
||||
|
||||
- Be respectful and inclusive
|
||||
- Help others learn and grow
|
||||
- Follow the [Code of Conduct](CODE_OF_CONDUCT.md)
|
||||
|
||||
## Questions?
|
||||
|
||||
Feel free to open an issue or discussion if you have questions!
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the MIT License.
|
||||
@@ -0,0 +1,571 @@
|
||||
# Depl0y Deployment Guide
|
||||
|
||||
This guide covers how to deploy Depl0y updates, make code changes, and manage the production environment.
|
||||
|
||||
## Table of Contents
|
||||
- [Development Workflow](#development-workflow)
|
||||
- [Making Code Changes](#making-code-changes)
|
||||
- [Deploying Changes](#deploying-changes)
|
||||
- [Creating a Release](#creating-a-release)
|
||||
- [Update Distribution](#update-distribution)
|
||||
- [Rollback Procedures](#rollback-procedures)
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
/home/administrator/depl0y/ # Development directory
|
||||
├── backend/ # Python FastAPI backend
|
||||
│ ├── app/
|
||||
│ │ ├── api/ # API endpoints
|
||||
│ │ ├── core/ # Core functionality
|
||||
│ │ ├── models/ # Database models
|
||||
│ │ └── services/ # Business logic
|
||||
│ ├── requirements.txt
|
||||
│ └── main.py
|
||||
├── frontend/ # Vue.js frontend
|
||||
│ ├── src/
|
||||
│ │ ├── views/ # Page components
|
||||
│ │ ├── services/ # API services
|
||||
│ │ ├── store/ # State management
|
||||
│ │ └── router/ # Routes
|
||||
│ ├── package.json
|
||||
│ └── vite.config.js
|
||||
├── scripts/ # Deployment scripts
|
||||
├── install.sh # One-line installer
|
||||
└── *.md # Documentation
|
||||
|
||||
/opt/depl0y/ # Production directory
|
||||
├── backend/ # Production backend
|
||||
├── frontend/dist/ # Built frontend assets
|
||||
└── ...
|
||||
|
||||
/var/lib/depl0y/ # Data directory
|
||||
├── db/ # SQLite database
|
||||
├── isos/ # ISO images
|
||||
├── cloud-images/ # Cloud image cache
|
||||
└── ssh_keys/ # SSH keys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Making Code Changes
|
||||
|
||||
### Backend Changes
|
||||
|
||||
1. **Edit Backend Code**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/backend
|
||||
# Edit files in app/ directory
|
||||
```
|
||||
|
||||
2. **Test Changes Locally (Optional)**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --host 127.0.0.1 --port 8001
|
||||
```
|
||||
|
||||
3. **Check Logs**
|
||||
```bash
|
||||
sudo journalctl -u depl0y-backend -f
|
||||
```
|
||||
|
||||
### Frontend Changes
|
||||
|
||||
1. **Edit Frontend Code**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/frontend
|
||||
# Edit files in src/ directory
|
||||
```
|
||||
|
||||
2. **Test Changes Locally (Optional)**
|
||||
```bash
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run dev
|
||||
# Access at http://localhost:5173
|
||||
```
|
||||
|
||||
3. **Check Console**
|
||||
- Open browser Developer Tools (F12)
|
||||
- Check Console for errors
|
||||
- Check Network tab for API calls
|
||||
|
||||
---
|
||||
|
||||
## Deploying Changes
|
||||
|
||||
### Quick Deploy Script
|
||||
|
||||
Create a deployment script for convenience:
|
||||
|
||||
```bash
|
||||
cat > /home/administrator/depl0y/deploy.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🚀 Deploying Depl0y..."
|
||||
|
||||
# Build frontend
|
||||
echo "📦 Building frontend..."
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Deploy frontend
|
||||
echo "📤 Deploying frontend..."
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
|
||||
# Deploy backend
|
||||
echo "📤 Deploying backend..."
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chmod -R 755 /opt/depl0y/backend
|
||||
|
||||
# Restart services
|
||||
echo "🔄 Restarting services..."
|
||||
sudo systemctl restart depl0y-backend
|
||||
sudo systemctl reload nginx
|
||||
|
||||
# Check status
|
||||
echo "✅ Checking status..."
|
||||
sleep 2
|
||||
sudo systemctl status depl0y-backend --no-pager | head -15
|
||||
|
||||
echo ""
|
||||
echo "✅ Deployment complete!"
|
||||
echo "Check logs: sudo journalctl -u depl0y-backend -f"
|
||||
EOF
|
||||
|
||||
chmod +x /home/administrator/depl0y/deploy.sh
|
||||
```
|
||||
|
||||
### Deploy with Script
|
||||
|
||||
```bash
|
||||
/home/administrator/depl0y/deploy.sh
|
||||
```
|
||||
|
||||
### Manual Deployment Steps
|
||||
|
||||
#### Deploy Backend Only
|
||||
|
||||
```bash
|
||||
# Copy backend files to production
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/
|
||||
|
||||
# Fix permissions
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chmod -R 755 /opt/depl0y/backend
|
||||
|
||||
# Restart backend service
|
||||
sudo systemctl restart depl0y-backend
|
||||
|
||||
# Check status
|
||||
sudo systemctl status depl0y-backend
|
||||
sudo journalctl -u depl0y-backend -n 50
|
||||
```
|
||||
|
||||
#### Deploy Frontend Only
|
||||
|
||||
```bash
|
||||
# Build frontend
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Deploy to production
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
|
||||
# Fix permissions
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
|
||||
# Reload nginx (optional, usually not needed)
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
#### Deploy Both (Full Deploy)
|
||||
|
||||
```bash
|
||||
# Build frontend
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Deploy frontend
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
|
||||
# Deploy backend
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chmod -R 755 /opt/depl0y/backend
|
||||
|
||||
# Restart services
|
||||
sudo systemctl restart depl0y-backend
|
||||
sudo systemctl reload nginx
|
||||
|
||||
# Verify
|
||||
sudo systemctl status depl0y-backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creating a Release
|
||||
|
||||
### 1. Update Version Number
|
||||
|
||||
Edit the version in the backend config:
|
||||
|
||||
```bash
|
||||
nano /home/administrator/depl0y/backend/app/core/config.py
|
||||
```
|
||||
|
||||
Change:
|
||||
```python
|
||||
APP_VERSION: str = "1.1.0" # Update this
|
||||
```
|
||||
|
||||
### 2. Update Release Notes
|
||||
|
||||
Edit the system updates endpoint:
|
||||
|
||||
```bash
|
||||
nano /home/administrator/depl0y/backend/app/api/system_updates.py
|
||||
```
|
||||
|
||||
Update the `release_notes` in the `/version` endpoint:
|
||||
```python
|
||||
"release_notes": f"""
|
||||
Depl0y {settings.APP_VERSION} Release Notes:
|
||||
|
||||
✨ New Features:
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
🔧 Improvements:
|
||||
- Improvement 1
|
||||
- Improvement 2
|
||||
|
||||
🐛 Bug Fixes:
|
||||
- Fix 1
|
||||
- Fix 2
|
||||
"""
|
||||
```
|
||||
|
||||
### 3. Deploy to Production
|
||||
|
||||
```bash
|
||||
/home/administrator/depl0y/deploy.sh
|
||||
```
|
||||
|
||||
### 4. Test Update Endpoint
|
||||
|
||||
```bash
|
||||
curl http://localhost/api/v1/system-updates/version
|
||||
```
|
||||
|
||||
Verify the version and release notes are correct.
|
||||
|
||||
---
|
||||
|
||||
## Update Distribution
|
||||
|
||||
Depl0y uses a **pull-based update system** where client instances pull updates from the main server (`deploy.agit8or.net`).
|
||||
|
||||
### How Updates Work
|
||||
|
||||
1. **Main Server** (deploy.agit8or.net)
|
||||
- Serves version information via `/api/v1/system-updates/version`
|
||||
- Provides update packages via `/api/v1/system-updates/download`
|
||||
- Hosts the installer via `/install.sh`
|
||||
|
||||
2. **Client Instances**
|
||||
- Check for updates by querying main server
|
||||
- Compare local version with latest version
|
||||
- Download and apply updates if available
|
||||
|
||||
### Making Main Server the Update Source
|
||||
|
||||
If this is your main update server (`deploy.agit8or.net`):
|
||||
|
||||
1. **Ensure the installer is accessible**
|
||||
```bash
|
||||
# The installer should be served by nginx
|
||||
curl http://deploy.agit8or.net/install.sh
|
||||
```
|
||||
|
||||
2. **Update the backend config if needed**
|
||||
```bash
|
||||
nano /home/administrator/depl0y/backend/app/api/system_updates.py
|
||||
```
|
||||
|
||||
Verify:
|
||||
```python
|
||||
UPDATE_SERVER = "http://deploy.agit8or.net"
|
||||
```
|
||||
|
||||
3. **Test the update endpoints**
|
||||
```bash
|
||||
# Version info
|
||||
curl http://deploy.agit8or.net/api/v1/system-updates/version
|
||||
|
||||
# Download package (requires auth)
|
||||
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
||||
http://deploy.agit8or.net/api/v1/system-updates/download \
|
||||
-o test-package.tar.gz
|
||||
```
|
||||
|
||||
### Client Update Process
|
||||
|
||||
When a client checks for updates (Settings → System Updates):
|
||||
|
||||
1. Client calls `/api/v1/system-updates/check`
|
||||
2. Backend queries main server at `http://deploy.agit8or.net/api/v1/system-updates/version`
|
||||
3. Compares versions
|
||||
4. If update available, shows "Install Update" button
|
||||
5. When clicked, downloads from `http://deploy.agit8or.net/api/v1/system-updates/download`
|
||||
6. Extracts, builds, deploys, and restarts
|
||||
|
||||
---
|
||||
|
||||
## Rollback Procedures
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
The update system creates automatic backups at:
|
||||
```
|
||||
/opt/depl0y-backups/backup-YYYYMMDD-HHMMSS/
|
||||
```
|
||||
|
||||
### Manual Rollback
|
||||
|
||||
1. **Stop the service**
|
||||
```bash
|
||||
sudo systemctl stop depl0y-backend
|
||||
```
|
||||
|
||||
2. **Restore from backup**
|
||||
```bash
|
||||
# Find latest backup
|
||||
ls -la /opt/depl0y-backups/
|
||||
|
||||
# Restore backend
|
||||
sudo cp -r /opt/depl0y-backups/backup-YYYYMMDD-HHMMSS/backend/* /opt/depl0y/backend/
|
||||
|
||||
# Restore frontend (if backed up)
|
||||
sudo cp -r /opt/depl0y-backups/backup-YYYYMMDD-HHMMSS/frontend/* /opt/depl0y/frontend/
|
||||
```
|
||||
|
||||
3. **Fix permissions**
|
||||
```bash
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
```
|
||||
|
||||
4. **Restart service**
|
||||
```bash
|
||||
sudo systemctl start depl0y-backend
|
||||
sudo systemctl status depl0y-backend
|
||||
```
|
||||
|
||||
### Manual Backup Before Changes
|
||||
|
||||
```bash
|
||||
# Create backup directory
|
||||
BACKUP_DIR="/opt/depl0y-backups/manual-$(date +%Y%m%d-%H%M%S)"
|
||||
sudo mkdir -p "$BACKUP_DIR"
|
||||
|
||||
# Backup backend
|
||||
sudo cp -r /opt/depl0y/backend "$BACKUP_DIR/"
|
||||
|
||||
# Backup frontend
|
||||
sudo cp -r /opt/depl0y/frontend "$BACKUP_DIR/"
|
||||
|
||||
# Backup database
|
||||
sudo cp -r /var/lib/depl0y/db "$BACKUP_DIR/"
|
||||
|
||||
echo "Backup created at $BACKUP_DIR"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Deployment Issues
|
||||
|
||||
### Issue: Backend Service Won't Start
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
sudo journalctl -u depl0y-backend -n 100
|
||||
```
|
||||
|
||||
**Common causes:**
|
||||
- Python syntax errors
|
||||
- Missing dependencies
|
||||
- Database connection issues
|
||||
- Port already in use
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check if port 8000 is in use
|
||||
sudo lsof -i :8000
|
||||
|
||||
# Reinstall dependencies if needed
|
||||
cd /opt/depl0y/backend
|
||||
sudo -u depl0y venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Issue: Frontend Shows Blank Page
|
||||
|
||||
**Check:**
|
||||
1. Browser console (F12) for JavaScript errors
|
||||
2. Nginx error logs: `sudo tail -f /var/log/nginx/depl0y_error.log`
|
||||
3. Verify build was successful
|
||||
4. Check file permissions
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Rebuild and redeploy
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/*
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist
|
||||
sudo chmod -R 755 /opt/depl0y/frontend/dist
|
||||
```
|
||||
|
||||
### Issue: API Calls Failing (500 Errors)
|
||||
|
||||
**Check backend logs:**
|
||||
```bash
|
||||
sudo journalctl -u depl0y-backend -f
|
||||
```
|
||||
|
||||
**Common causes:**
|
||||
- Backend crashed
|
||||
- Database errors
|
||||
- API endpoint errors
|
||||
|
||||
**Quick restart:**
|
||||
```bash
|
||||
sudo systemctl restart depl0y-backend
|
||||
```
|
||||
|
||||
### Issue: Changes Not Appearing
|
||||
|
||||
**For backend:**
|
||||
```bash
|
||||
# Make sure you restarted the service
|
||||
sudo systemctl restart depl0y-backend
|
||||
|
||||
# Verify files were copied
|
||||
ls -la /opt/depl0y/backend/app/api/
|
||||
```
|
||||
|
||||
**For frontend:**
|
||||
```bash
|
||||
# Make sure you rebuilt
|
||||
cd /home/administrator/depl0y/frontend
|
||||
npm run build
|
||||
|
||||
# Verify files were copied
|
||||
ls -la /opt/depl0y/frontend/dist/
|
||||
|
||||
# Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring and Maintenance
|
||||
|
||||
### Check Service Status
|
||||
```bash
|
||||
sudo systemctl status depl0y-backend
|
||||
sudo systemctl status nginx
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# Live backend logs
|
||||
sudo journalctl -u depl0y-backend -f
|
||||
|
||||
# Last 100 lines
|
||||
sudo journalctl -u depl0y-backend -n 100
|
||||
|
||||
# Nginx access logs
|
||||
sudo tail -f /var/log/nginx/depl0y_access.log
|
||||
|
||||
# Nginx error logs
|
||||
sudo tail -f /var/log/nginx/depl0y_error.log
|
||||
```
|
||||
|
||||
### Restart Services
|
||||
```bash
|
||||
# Backend only
|
||||
sudo systemctl restart depl0y-backend
|
||||
|
||||
# Nginx only
|
||||
sudo systemctl reload nginx
|
||||
|
||||
# Both
|
||||
sudo systemctl restart depl0y-backend
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
### Check Disk Space
|
||||
```bash
|
||||
df -h /opt/depl0y
|
||||
df -h /var/lib/depl0y
|
||||
```
|
||||
|
||||
### Clean Up Old Backups
|
||||
```bash
|
||||
# List backups
|
||||
ls -lah /opt/depl0y-backups/
|
||||
|
||||
# Remove old backups (keep last 5)
|
||||
cd /opt/depl0y-backups/
|
||||
ls -t | tail -n +6 | xargs sudo rm -rf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Deploy Everything
|
||||
```bash
|
||||
cd /home/administrator/depl0y/frontend && npm run build && \
|
||||
sudo rm -rf /opt/depl0y/frontend/dist/* && \
|
||||
sudo cp -r dist/* /opt/depl0y/frontend/dist/ && \
|
||||
sudo cp -r /home/administrator/depl0y/backend/* /opt/depl0y/backend/ && \
|
||||
sudo chown -R www-data:www-data /opt/depl0y/frontend/dist && \
|
||||
sudo chown -R depl0y:depl0y /opt/depl0y/backend && \
|
||||
sudo systemctl restart depl0y-backend
|
||||
```
|
||||
|
||||
### Check Everything
|
||||
```bash
|
||||
sudo systemctl status depl0y-backend nginx && \
|
||||
curl -s http://localhost/api/v1/system-updates/version | head -5 && \
|
||||
sudo journalctl -u depl0y-backend -n 10
|
||||
```
|
||||
|
||||
### Emergency Restart
|
||||
```bash
|
||||
sudo systemctl restart depl0y-backend nginx && \
|
||||
sleep 2 && \
|
||||
sudo systemctl status depl0y-backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**For more information, see:**
|
||||
- [INSTALL.md](INSTALL.md) - Installation guide
|
||||
- [README.md](README.md) - Project overview
|
||||
- [CLOUD_IMAGES_GUIDE.md](CLOUD_IMAGES_GUIDE.md) - Cloud images setup
|
||||
+163
@@ -0,0 +1,163 @@
|
||||
# Depl0y Installation Guide
|
||||
|
||||
## One-Line Installation
|
||||
|
||||
Install Depl0y with a single command:
|
||||
|
||||
```bash
|
||||
curl -fsSL http://deploy.agit8or.net/install.sh | sudo bash
|
||||
```
|
||||
|
||||
That's it! The installer will:
|
||||
- Install all dependencies (Python, Node.js, nginx, etc.)
|
||||
- Create the depl0y system user
|
||||
- Download and install the latest version from deploy.agit8or.net
|
||||
- Configure the backend service
|
||||
- Configure nginx as reverse proxy
|
||||
- Set up proper permissions
|
||||
|
||||
## After Installation
|
||||
|
||||
1. **Access the Web Interface**
|
||||
```
|
||||
http://YOUR_SERVER_IP
|
||||
```
|
||||
|
||||
2. **Default Credentials**
|
||||
```
|
||||
Username: admin
|
||||
Password: admin
|
||||
```
|
||||
|
||||
⚠️ **IMPORTANT:** Change the default password immediately after first login!
|
||||
|
||||
3. **Add Your Proxmox Host**
|
||||
- Go to Settings → Proxmox Hosts
|
||||
- Add your Proxmox datacenter details
|
||||
- Generate API token in Proxmox and add it
|
||||
|
||||
4. **Enable Cloud Images** (Optional but Recommended)
|
||||
- Go to Settings → Cloud Images
|
||||
- Click "🚀 Enable Cloud Images Now"
|
||||
- Enter your Proxmox root password
|
||||
- Wait ~30 seconds for automated setup
|
||||
|
||||
5. **Configure Inter-Node SSH** (For Multi-Node Clusters Only)
|
||||
- Go to Settings → Proxmox Cluster Inter-Node SSH
|
||||
- Click "🔐 Enable Inter-Node SSH"
|
||||
- Enter your Proxmox root password
|
||||
- Wait ~30 seconds for automated setup
|
||||
|
||||
## Manual Installation
|
||||
|
||||
If you prefer to install manually, see [README.md](README.md) for detailed instructions.
|
||||
|
||||
## Deployment Guide
|
||||
|
||||
For developers and operations teams who need to deploy code changes or manage updates:
|
||||
|
||||
📖 **See [DEPLOYMENT.md](DEPLOYMENT.md)** for complete deployment procedures including:
|
||||
- Making and deploying code changes
|
||||
- Creating releases and updates
|
||||
- Rollback procedures
|
||||
- Troubleshooting deployment issues
|
||||
|
||||
## Requirements
|
||||
|
||||
- Ubuntu 20.04+ or Debian 11+ (recommended)
|
||||
- 2GB RAM minimum
|
||||
- 20GB disk space minimum
|
||||
- Root access
|
||||
- Network access to your Proxmox server
|
||||
|
||||
## Update Mechanism
|
||||
|
||||
Depl0y includes an automatic update system:
|
||||
|
||||
1. **Check for Updates**
|
||||
- Go to Settings → System Updates
|
||||
- Click "🔍 Check for Updates"
|
||||
|
||||
2. **Install Updates**
|
||||
- If an update is available, click "⬇️ Install Update"
|
||||
- The system will download from deploy.agit8or.net
|
||||
- Service restarts automatically
|
||||
- Page reloads after update completes
|
||||
|
||||
## Source Server
|
||||
|
||||
The main Depl0y server is hosted at:
|
||||
- **URL:** http://deploy.agit8or.net
|
||||
- **Purpose:** Source for installations and updates
|
||||
- **Updates:** All instances pull updates from this server
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Installation Failed
|
||||
```bash
|
||||
# Check logs
|
||||
sudo journalctl -u depl0y-backend -n 50
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart depl0y-backend
|
||||
|
||||
# Check nginx
|
||||
sudo nginx -t
|
||||
sudo systemctl status nginx
|
||||
```
|
||||
|
||||
### Cannot Access Web Interface
|
||||
```bash
|
||||
# Check if service is running
|
||||
sudo systemctl status depl0y-backend
|
||||
|
||||
# Check nginx
|
||||
sudo systemctl status nginx
|
||||
|
||||
# Check firewall
|
||||
sudo ufw status
|
||||
sudo ufw allow 80/tcp
|
||||
```
|
||||
|
||||
### Database Issues
|
||||
```bash
|
||||
# Reset database (WARNING: Deletes all data!)
|
||||
sudo systemctl stop depl0y-backend
|
||||
sudo rm -rf /var/lib/depl0y/db/*
|
||||
sudo systemctl start depl0y-backend
|
||||
```
|
||||
|
||||
## Uninstallation
|
||||
|
||||
To completely remove Depl0y:
|
||||
|
||||
```bash
|
||||
# Stop services
|
||||
sudo systemctl stop depl0y-backend
|
||||
sudo systemctl disable depl0y-backend
|
||||
|
||||
# Remove files
|
||||
sudo rm -rf /opt/depl0y
|
||||
sudo rm -rf /var/lib/depl0y
|
||||
sudo rm /etc/systemd/system/depl0y-backend.service
|
||||
sudo rm /etc/nginx/sites-enabled/depl0y
|
||||
sudo rm /etc/nginx/sites-available/depl0y
|
||||
sudo rm /etc/sudoers.d/depl0y
|
||||
|
||||
# Remove user
|
||||
sudo userdel -r depl0y
|
||||
|
||||
# Reload services
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
- **Documentation:** http://deploy.agit8or.net/docs
|
||||
- **Issues:** Report bugs and request features on GitHub
|
||||
- **Updates:** Automatic updates from deploy.agit8or.net
|
||||
|
||||
---
|
||||
|
||||
**Depl0y** - Automated VM Deployment Panel for Proxmox VE
|
||||
@@ -0,0 +1,128 @@
|
||||
# Proxmox API Tokens for 2FA Authentication
|
||||
|
||||
When your Proxmox VE server has Two-Factor Authentication (2FA) enabled, you need to use **API Tokens** instead of password authentication for programmatic access.
|
||||
|
||||
## Why API Tokens?
|
||||
|
||||
- **Bypass 2FA**: API tokens don't require 2FA codes, making them perfect for automated systems
|
||||
- **More Secure**: Can be revoked without changing your main password
|
||||
- **Fine-grained Permissions**: Can be restricted to specific operations
|
||||
- **Audit Trail**: API token usage is logged separately
|
||||
|
||||
## Creating an API Token in Proxmox
|
||||
|
||||
### Step 1: Log into Proxmox Web Interface
|
||||
|
||||
1. Navigate to your Proxmox web interface: `https://your-proxmox-host:8006`
|
||||
2. Log in with your credentials (including 2FA if enabled)
|
||||
|
||||
### Step 2: Navigate to API Tokens
|
||||
|
||||
1. Click on **Datacenter** in the left sidebar
|
||||
2. Expand **Permissions**
|
||||
3. Click on **API Tokens**
|
||||
|
||||
### Step 3: Create a New Token
|
||||
|
||||
1. Click the **Add** button at the top
|
||||
2. Fill in the token details:
|
||||
- **User**: Select the user (e.g., `root@pam`)
|
||||
- **Token ID**: Give it a meaningful name (e.g., `depl0y`)
|
||||
- **Privilege Separation**: **UNCHECK** this box (important!)
|
||||
- Unchecking this gives the token the same permissions as the user
|
||||
- Checking it would create a token with limited permissions
|
||||
- **Expiration**: Leave empty for no expiration, or set an expiration date
|
||||
|
||||
3. Click **Add**
|
||||
|
||||
### Step 4: Save the Token Secret
|
||||
|
||||
**IMPORTANT**: After clicking Add, you'll see a screen showing the **Token Secret**.
|
||||
|
||||
```
|
||||
Token ID: root@pam!depl0y
|
||||
Token Secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
```
|
||||
|
||||
**Copy and save this secret immediately!** You won't be able to see it again.
|
||||
|
||||
## Using API Tokens in Depl0y
|
||||
|
||||
When adding a Proxmox host in Depl0y:
|
||||
|
||||
1. Go to **Proxmox Hosts** → **+ Add Host**
|
||||
2. Fill in basic details:
|
||||
- Name: Any name for your reference
|
||||
- Hostname/IP: Your Proxmox server address
|
||||
- Port: 8006 (default)
|
||||
- Username: `root@pam` (the user who owns the token)
|
||||
|
||||
3. **Check** the box: "Use API Token (recommended for 2FA-enabled Proxmox)"
|
||||
|
||||
4. Enter token details:
|
||||
- **API Token ID**: You can use either format:
|
||||
- **Full format**: `root@pam!depl0y` (the complete Token ID from Proxmox)
|
||||
- **Short format**: `depl0y` (just the token name)
|
||||
- **API Token Secret**: The UUID-like secret you copied earlier
|
||||
|
||||
5. Optionally check "Verify SSL Certificate" if you have a valid SSL cert
|
||||
|
||||
6. Click **Add Host**
|
||||
|
||||
## Example
|
||||
|
||||
If Proxmox shows your token as:
|
||||
```
|
||||
Token ID: root@pam!mytoken
|
||||
Token Secret: 12345678-1234-1234-1234-123456789abc
|
||||
```
|
||||
|
||||
In Depl0y, you can enter **either**:
|
||||
|
||||
**Option 1 (Full format - Recommended):**
|
||||
- Username: `root@pam` (can be anything, will be extracted from token)
|
||||
- API Token ID: `root@pam!mytoken`
|
||||
- API Token Secret: `12345678-1234-1234-1234-123456789abc`
|
||||
|
||||
**Option 2 (Short format):**
|
||||
- Username: `root@pam`
|
||||
- API Token ID: `mytoken`
|
||||
- API Token Secret: `12345678-1234-1234-1234-123456789abc`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Failed
|
||||
- Make sure "Privilege Separation" was UNCHECKED when creating the token
|
||||
- Confirm the token hasn't expired
|
||||
- Check that the Proxmox host is reachable from your Depl0y server
|
||||
- Verify the token secret is correct (it's case-sensitive)
|
||||
- Try using the full token format: `root@pam!tokenname`
|
||||
|
||||
### Permission Denied
|
||||
- Ensure "Privilege Separation" was unchecked when creating the token
|
||||
- Verify the user account has sufficient permissions
|
||||
- Check Proxmox logs: `/var/log/pve/tasks/`
|
||||
|
||||
### Token Not Working After Creation
|
||||
- API tokens may need a few seconds to become active
|
||||
- Try refreshing the Proxmox web interface
|
||||
- Log out and back in to Proxmox
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Use Separate Tokens**: Create different tokens for different applications
|
||||
2. **Set Expiration**: Consider setting expiration dates for tokens
|
||||
3. **Revoke Unused Tokens**: Regularly audit and remove tokens you no longer use
|
||||
4. **Store Securely**: Keep token secrets secure, like passwords
|
||||
5. **Monitor Usage**: Check Proxmox logs for API token usage
|
||||
|
||||
## Revoking a Token
|
||||
|
||||
To revoke an API token:
|
||||
|
||||
1. Go to **Datacenter** → **Permissions** → **API Tokens**
|
||||
2. Select the token you want to revoke
|
||||
3. Click **Remove**
|
||||
4. Confirm the removal
|
||||
|
||||
The token will be immediately revoked and can no longer be used.
|
||||
Reference in New Issue
Block a user