Skip to content

Installation Guide

Get cv4pve-admin up and running in minutes with Docker.

Prerequisites

Before installing cv4pve-admin, ensure you have:

  • Docker 24.0 or later (Install Docker)
  • Docker Compose 2.20 or later (included with Docker Desktop)
  • Minimum 2GB RAM available for containers
  • 10GB disk space for application and database
  • Proxmox VE 6.2 or later to manage

System Requirements

For production use, we recommend at least 4GB RAM and 20GB disk space.

Quick Installation

The fastest way to get started is using our automated installer:

curl -fsSL https://raw.githubusercontent.com/Corsinvest/cv4pve-admin/master/install.sh | bash

The installer will:

  1. Welcome you and explain the process
  2. Ask which edition you want (CE or EE)
  3. Ask which version/tag to use (default: latest)
  4. Request PostgreSQL password (minimum 8 characters)
  5. Download all necessary files from GitHub
  6. Configure environment variables
  7. Start all Docker containers
  8. Display access information
irm https://raw.githubusercontent.com/Corsinvest/cv4pve-admin/master/install.ps1 | iex

The installer will:

  1. Welcome you and explain the process
  2. Ask which edition you want (CE or EE)
  3. Ask which version/tag to use (default: latest)
  4. Request PostgreSQL password (minimum 8 characters)
  5. Download all necessary files from GitHub
  6. Configure environment variables
  7. Start all Docker containers
  8. Display access information

Installation Complete

After installation completes, open your browser to http://localhost:8080

First Time Setup

After installation, access the application:

  1. Open your browser to http://localhost:8080
  2. Login with default credentials:
  3. Username: admin@local
  4. Password: Password123!
  5. Configure your first Proxmox cluster:
  6. After login, the system automatically opens the cluster configuration dialog
  7. Enter your Proxmox VE details:
    • Host: Proxmox VE hostname or IP address
    • Username: API user (e.g., root@pam or token)
    • Password/Token: Credentials for authentication
    • Node: Proxmox node name
  8. Change the default password:
  9. Navigate to your Profile settings
  10. Update the default password immediately

Security Alert

Change the default admin@local/Password123! credentials immediately after setup!

Next Steps

After installation, you can:

  • Configuration - Customize application settings, security, and logging
  • Modules - Explore available modules and features

Advanced Docker Setup

For detailed Docker deployment information, see the complete Docker documentation:

📖 Docker Deployment Guide

Includes: - Docker Compose commands reference - Backup and restore procedures - Update management (automatic and manual) - Testing pre-release versions (RC) - Custom configuration with appsettings.extra.json - Troubleshooting and common issues - Running multiple instances - Security best practices

Environment Variables

Key settings in .env:

Variable Default Description
POSTGRES_PASSWORD cv4pve-admin PostgreSQL database password (change before production!)
CV4PVE_ADMIN_PORT 8080 Application web port
CV4PVE_ADMIN_TAG latest Docker image tag/version
TZ Europe/Rome Container timezone

Complete Configuration

For all available environment variables and detailed descriptions, see the .env file in your installation directory. The file includes configuration for PostgreSQL, ports, data directories, timezone, backup location, and Watchtower settings.

Port Configuration

To change the application port, edit .env:

CV4PVE_ADMIN_PORT=8080

Then restart services:

docker compose restart

Testing Pre-Release Versions

To test release candidates or specific versions:

# Edit .env file
sed -i '' 's/CV4PVE_ADMIN_TAG=.*/CV4PVE_ADMIN_TAG=rc2/' .env

# Or manually edit the file
nano .env

# Restart containers
docker compose down && docker compose up -d

# Edit .env file
(Get-Content .env) -replace 'CV4PVE_ADMIN_TAG=.*', 'CV4PVE_ADMIN_TAG=rc2' | Set-Content .env

# Or manually edit the file
notepad .env

# Restart containers
docker compose down; docker compose up -d

Available tags:

  • latest - Latest stable release
  • rc1, rc2, etc. - Release candidates
  • beta1, beta2, etc. - Beta release
  • v1.0.0, v1.1.0, etc. - Specific versions

Management Commands

The adminctl script provides convenient management commands:

# View logs
./adminctl logs

# Restart services
./adminctl restart

# Stop services
./adminctl stop

# Start services
./adminctl start

# Open PgWeb database interface
./adminctl pgweb

# Backup database
./adminctl backup

# View status
./adminctl status

PgWeb Access

PgWeb provides a web interface for PostgreSQL at http://localhost:8082

Troubleshooting

Containers Won't Start

Check logs for errors:

docker compose logs cv4pve-admin

Common issues:

  • Port already in use: Change CV4PVE_ADMIN_PORT in .env
  • Permission denied: Ensure user has Docker permissions
  • Out of memory: Increase Docker memory limit

Database Connection Failed

Verify PostgreSQL is running:

docker compose ps postgres
docker compose logs postgres

Check password matches in .env file.

Application Won't Load

  1. Check all containers are healthy: 

    docker compose ps

  2. Verify port forwarding: 

    curl http://localhost:5000

  3. Check application logs: 

    docker compose logs cv4pve-admin -f

Reset Everything

To completely reset and start fresh:

# Stop and remove all containers
docker compose down -v

# Remove images (optional)
docker compose down --rmi all

# Start fresh
docker compose up -d

Data Loss

Using -v flag will delete all data including database!

Updating

cv4pve-admin includes automatic updates via Watchtower, but you can also update manually:

Automatic Updates (Watchtower)

Watchtower automatically checks for new images and updates containers. It runs daily by default.

To disable automatic updates, remove the watchtower service from docker-compose.yaml.

Manual Update

# Pull latest images
docker compose pull

# Restart containers with new images
docker compose up -d

# Clean up old images
docker image prune -f

Update to Specific Version

# Edit .env to change version
sed -i 's/CV4PVE_ADMIN_TAG=.*/CV4PVE_ADMIN_TAG=v1.2.0/' .env

# Pull and restart
docker compose pull && docker compose up -d

Multiple Instances

To run multiple instances (e.g., production and testing):

  1. Create separate directories: 

    mkdir cv4pve-admin-prod
mkdir cv4pve-admin-test

  2. Copy configuration to each: 

    cp -r cv4pve-admin/src/docker/* cv4pve-admin-prod/
cp -r cv4pve-admin/src/docker/* cv4pve-admin-test/

  3. Edit .env in each directory with different ports: 

    # Production
CV4PVE_ADMIN_PORT=5000

# Testing
CV4PVE_ADMIN_PORT=5001

  4. Start each instance from its directory: 

    cd cv4pve-admin-prod && docker compose up -d
cd ../cv4pve-admin-test && docker compose up -d

Uninstallation

To completely remove cv4pve-admin:

# Stop and remove containers
docker compose down

# Remove volumes (all data will be lost!)
docker compose down -v

# Remove images
docker rmi corsinvest/cv4pve-admin:latest
docker rmi postgres:17-alpine

# Remove files
cd .. && rm -rf cv4pve-admin

Next Steps

After successful installation:

  1. Secure your installation - Change default passwords
  2. Add Proxmox clusters - Configure your infrastructure
  3. Set up automated snapshots - Configure backup policies
  4. Explore the dashboard - Familiarize yourself with features
  5. Read the User Guide - Learn advanced features

Continue to User Guide →

Getting Help

If you encounter issues: