Installation Guide

Introduction

Infinibay manages virtual machines on Linux hosts using libvirt and KVM. The installer sets up system packages, database, repositories, and services.

Installation guide for Ubuntu 23.10+ and Fedora 37+.

For detailed technical reference, see the installer repository.

Installation Methods

Infinibay offers two installation methods:

🎯 LXD Container (Recommended)

Status: In active development - ready in weeks

The easiest way to deploy Infinibay is using LXD containers with lxc/lxd-compose. This method provides:

• One-command deployment: lxc launch infinibay or lxd-compose up
• Isolated environment: Complete isolation from host system
• Easy updates: Simple container image updates
• Resource limits: Built-in CPU/memory constraints
• Snapshots: Instant backup and restore
• Minimal host changes: No system package modifications

Best for: Production deployments, testing, isolated environments

For the latest LXD deployment status, see the LXD repository.

📦 Direct Installation (Available Now)

Traditional installation directly on the host system. Provides maximum performance and full system access but modifies system packages and services.

Best for: Development, bare-metal performance, custom configurations

Continue reading below for direct installation instructions.

System Requirements

Supported Operating Systems

• Ubuntu 23.10 or later
• Fedora 37 or later

Hardware Requirements

• CPU: x86_64 processor with hardware virtualization support (Intel VT-x or AMD-V)
  • egrep -c '(vmx|svm)' /proc/cpuinfo (should return > 0)
• RAM: Minimum 8GB (16GB+ recommended for running multiple VMs)
• Disk Space:
  • 10GB minimum for /opt/infinibay/ (code and dependencies)
  • Additional space for VM disk images (varies by usage)
  • Recommended: 100GB+ SSD for optimal VM performance

Software Prerequisites

• Python 3.8 or later: Required for running the installer
• Root/sudo access: Installation modifies system packages and services
• Internet connectivity: Required for downloading packages, repositories, and ISOs

Optional Dependencies

• asciimatics: Enhances installation banner

  pip3 install asciimatics
  

Pre-Installation Checklist

Verify system requirements:

# Verify KVM support (should return > 0)
egrep -c '(vmx|svm)' /proc/cpuinfo

# Check disk space (ensure 10GB+ free in /opt)
df -h /opt

# Verify Python version (should be 3.8+)
python3 --version

# Ensure sudo access
sudo -v

# Check OS version
cat /etc/os-release

Direct Installation Guide

Note: This section covers traditional direct installation. For LXD container deployment (recommended when available), see the section above.

Basic Installation

# Clone the installer repository
git clone https://github.com/infinibay/installer.git
cd installer

# Run the installer
sudo python3 install.py

What happens automatically:

• Detects host IP
• Generates database password
• Uses default libvirt network
• Installs to /opt/infinibay/
• Creates systemd services
• Configures PostgreSQL
• Builds repositories

Installation Summary

At the end of installation, you'll see a summary (example output, values may differ if flags are used):

╔═══════════════════════════════════════════════════════════════╗
║              INFINIBAY INSTALLATION COMPLETE!                  ║
╠═══════════════════════════════════════════════════════════════╣
║ Frontend URL:      http://192.168.1.100:3000                  ║
║ Backend URL:       http://192.168.1.100:4000                  ║
║ GraphQL Playground: http://192.168.1.100:4000/graphql         ║
║                                                                ║
║ Admin Credentials:                                             ║
║   Email:    admin@example.com                                  ║
║   Password: password                                           ║
║                                                                ║
║ Database Password: [generated password shown here]             ║
╚═══════════════════════════════════════════════════════════════╝

Save these credentials for accessing the web interface.

Installation Options

Custom Database Configuration

# Custom password
sudo python3 install.py --db-password=MySecurePassword123

# Remote PostgreSQL
sudo python3 install.py --db-host=192.168.1.50 --db-port=5432

# Custom database and user names
sudo python3 install.py --db-name=infinibay_prod --db-user=infinibay_prod

Network Configuration

# Specify host IP
sudo python3 install.py --host-ip=192.168.1.100

# Use specific libvirt network
sudo python3 install.py --libvirt-network-name=br0

Custom Ports

sudo python3 install.py --backend-port=8080 --frontend-port=8081

Custom Installation Directory

# Custom install directory
sudo python3 install.py --install-dir=/opt/custom/path

# Separate data directory for VM disks/ISOs
sudo python3 install.py --install-dir=/opt/infinibay --data-dir=/mnt/storage/infinibay

Execution Modes

# Dry run
sudo python3 install.py --dry-run

# Verbose logging
sudo python3 install.py --verbose

# Combined
sudo python3 install.py --dry-run --verbose

Complete Example

sudo python3 install.py \
  --host-ip=192.168.1.100 \
  --db-password=SecurePass2024! \
  --libvirt-network-name=br0 \
  --backend-port=4000 \
  --frontend-port=3000 \
  --install-dir=/opt/infinibay \
  --data-dir=/mnt/storage/infinibay \
  --skip-windows-isos \
  --verbose

Development Mode Installation

Development mode: Install from local workspace instead of cloning from GitHub.

cd /home/andres/infinibay
sudo python3 installer/install.py --install-dir=/home/andres/infinibay

Or use the helper script:

cd /home/andres/infinibay
sudo ./installer/install-dev.sh

The installer detects existing .git directories and skips cloning, builds in place, and restores file ownership after builds.

Installation Process Explained

The installer runs five phases:

Phase 1: Framework Initialization

Validates OS version, checks root access, detects host IP, generates database password.

Phase 2: System Dependencies

Installs Node.js, PostgreSQL, Redis, QEMU/KVM, libvirt, Rust, build tools, and mingw-w64.

Phase 3: Database Setup

Creates PostgreSQL database and user. If connection fails, the installer provides troubleshooting steps.

Phase 4: Repository Setup

Builds libvirt-node (Rust addon), backend (npm + Prisma), frontend (Next.js), infiniservice (Rust binaries for Linux and Windows).

Phase 5: Configuration & Services

Generates .env files with database URL and host IP, runs Prisma migrations, creates systemd services, downloads ISOs.

Network Configuration

Automatic Network Detection

The installer detects and configures libvirt networks automatically. Prefers default network, or creates infinibay NAT network if none exist.

Network Modes

• NAT (default): VMs use private IPs, access internet via host
• Bridged: VMs get IPs from physical network, visible to other hosts
• Isolated: VMs can only talk to host, no internet

Custom Network Setup

# List available networks
virsh net-list --all

# Use specific network
sudo python3 install.py --libvirt-network-name=your-network

Command-Line Reference

Complete reference of all installation options. Defaults shown below are subject to change; the installer output is the source of truth.

Database Configuration

Admin User Configuration

Network Configuration

Installation Paths

Repository Options

Installation Options

Execution Modes

Version Information

# Check installer version
python3 install.py --version
# Output: Infinibay Installer v1.0.0

Usage Examples

# Basic installation
sudo python3 install.py

# Custom password
sudo python3 install.py --db-password=SecurePass2024!

# Custom network
sudo python3 install.py --host-ip=192.168.1.100 --libvirt-network-name=br0

# Development mode (from workspace root)
sudo python3 installer/install.py --install-dir=/home/andres/infinibay

Troubleshooting Common Issues

Permission Denied

Run with sudo:

sudo python3 install.py

Unsupported OS Version

Requires Ubuntu 23.10+ or Fedora 37+. Upgrade your OS.

Database Connection Failed

Check service status and pg_hba.conf authentication. The installer provides interactive troubleshooting if connection fails.

Invalid Port Number in Database URL

The installer URL-encodes passwords automatically. If you still see errors, use a simple password without special characters.

GitHub Authentication Required

Generate a personal access token at https://github.com/settings/tokens with repo scope. Use it as your password when Git prompts for credentials. Or use SSH keys.

Build Failures

Check internet connectivity and disk space. Run with --verbose for details.

libvirt-node Integrity Checksum Error

The installer cleans npm cache automatically. If you still see checksum errors:

cd /opt/infinibay/backend
npm cache clean --force
rm package-lock.json
npm install

Port Already in Use

Use --backend-port and --frontend-port to avoid conflicts. Check with lsof -i :3000.

Network Bridge Issues

Check libvirt network status with virsh net-list --all. Start default network if inactive.

Post-Installation Verification

Check service status:

systemctl status infinibay-backend infinibay-frontend

Access web interface at http://<your-host-ip>:3000 and GraphQL playground at http://<your-host-ip>:4000/graphql.

Check logs:

journalctl -u infinibay-backend -f
journalctl -u infinibay-frontend -f

Service Management

# Start/stop/restart
sudo systemctl start infinibay-backend infinibay-frontend
sudo systemctl stop infinibay-backend infinibay-frontend
sudo systemctl restart infinibay-backend infinibay-frontend

# Check status
sudo systemctl status infinibay-backend infinibay-frontend

# View logs
sudo journalctl -u infinibay-backend -f

# Enable/disable autostart
sudo systemctl enable infinibay-backend infinibay-frontend
sudo systemctl disable infinibay-backend infinibay-frontend

# Reload configuration after editing service files
sudo systemctl daemon-reload
sudo systemctl restart infinibay-backend infinibay-frontend

Uninstallation

Run from the installer repo or use the full path to uninstall.py:

cd ~/installer  # or wherever you cloned the installer

Additional flags: --dry-run, --yes, --verbose, --install-dir, --db-name, --db-user

Next Steps

1. Access http://<your-host-ip>:3000
2. Log in with admin@example.com / password
3. Change admin password in Settings → Account
4. Create departments and configure firewall rules
5. Navigate to VMs → Create VM

Documentation:

• Backend Architecture
• Frontend Architecture
• GraphQL API

Upgrading to LXD Deployment

Once LXD container deployment becomes available, you can migrate your existing installation:

1. Export data: Backup VMs, database, and configuration
2. Deploy LXD container: Use lxd-compose up or lxc launch infinibay
3. Import data: Restore backup into container
4. Uninstall direct: Remove host installation with uninstall.py --remove-files

LXD deployment will be documented separately when released.

Additional Resources

• Installer Repository - Direct installation scripts
• LXD Repository - Container deployment (in development)
• GitHub Issues