Installation

Prerequisites

PHP & System Requirements

  • PHP 8.4+ with extensions: mysql, xml, curl, ldap, mbstring, zip, openssl
  • MySQL/MariaDB or SQLite (SQLite is used by default in SNAP installations)
  • Apache (or compatible web server) with SSL, proxy, and rewrite modules
  • Node.js 24 (for the WebSocket event server)
  • Composer (PHP dependency manager)
  • Cron (for scheduled tasks via Crunz)

Initialize LXD or Incus

An opinionated guide on setting up LXD/Incus is forthcoming. For now, refer to these resources:

Make LXD/Incus Available Over the Network

When LXDMosaic connects to each LXD/Incus host for the first time, it authenticates using a trust token or trust password. This allows LXDMosaic to deploy a trust certificate for future communications.

First, make the daemon listen on the network:

bash 
# For LXD
lxc config set core.https_address :8443

# For Incus
incus config set core.https_address :8443

Token-based Authentication (Recommended)

Token-based authentication is required for LXD 6+ and recommended for all supported versions:

bash 
# For LXD
lxc config trust add --name lxdmosaic

# For Incus
incus config trust add --name lxdmosaic

Trust Password (Legacy — Not Recommended)

For older versions of LXD that do not support token-based authentication, you may use a trust password. This approach has security drawbacks and is not recommended:

bash 
# For LXD
lxc config set core.trust_password some-secret-string

# For Incus
incus config set core.trust_password some-secret-string

Note: If you connect to an LXD or Incus cluster, LXDMosaic will attempt to add all cluster members using the same credentials.

Installing LXDMosaic on Ubuntu / Debian

Using the Automated Script

The automated install script clones the repository and configures all dependencies. It should be run as root inside an Ubuntu container:

bash 
# Launch an Ubuntu container
lxc launch ubuntu: lxdMosaic

# Connect to the container console
lxc exec lxdMosaic bash

# Download the installation script
curl -o installLxdMosaic.sh https://raw.githubusercontent.com/turtle0x1/LxdMosaic/master/examples/install_with_clone.sh

# Make the script executable
chmod +x installLxdMosaic.sh

# Run the installer
./installLxdMosaic.sh

The script handles the following automatically:

  1. Installs Apache, PHP 8.4, MySQL, Node.js (via nvm), Composer, and required PHP extensions.
  2. Clones the LXDMosaic repository into /var/www/LxdMosaic.
  3. Creates required directories (sensitiveData/certs, sensitiveData/backups) with proper ownership.
  4. Configures the database and runs all migrations.
  5. Sets up the Apache virtual host with SSL.
  6. Installs and starts the Node.js WebSocket service via systemd.
  7. Configures the cron job for scheduled background tasks.

Configuration

Environment Variables

Copy .env.dist to .env and configure your settings:

bash 
cp .env.dist .env

Key environment variables:

Variable Description Example
DB_HOST Database host localhost
DB_USER Database username lxd
DB_PASS Database password your-secure-password
DB_NAME Database name LXD_Manager
DB_SQLITE SQLite database path (alternative to MySQL) /path/to/lxdMosaic.db
LXD_CERTS_DIR Directory for LXD client certificates /var/www/LxdMosaic/src/sensitiveData/certs/
CERT_PATH SSL certificate path /etc/ssl/certs/ssl-cert-snakeoil.pem
CERT_PRIVATE_KEY SSL private key path /etc/ssl/private/ssl-cert-snakeoil.key

To use SQLite instead of MySQL, set DB_SQLITE to a valid file path and leave the other DB variables empty.

Apache Configuration

The project ships with a pre-configured Apache vhost file at examples/lxd_manager.conf. It includes SSL termination, proxy rules for the Node.js WebSocket server, and rewrite rules.

bash 
# Copy the config to Apache sites-available
cp examples/lxd_manager.conf /etc/apache2/sites-available/

# Enable required modules
a2enmod ssl headers rewrite proxy proxy_wstunnel proxy_http proxy_balancer

# Enable the site
a2ensite lxd_manager

# Disable the default sites
a2dissite 000-default default-ssl

# Restart Apache
systemctl restart apache2

Node.js WebSocket Service

The Node.js service handles real-time WebSocket connections for instance consoles, operations, and events. It is managed as a systemd service:

bash 
cp examples/lxdmosaic_node.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable lxdmosaic_node
sudo systemctl start lxdmosaic_node

Cron Tasks

LXDMosaic uses Crunz for scheduling background tasks. Add the following line to your system crontab (/etc/crontab):

plaintext 
* * * * * www-data cd /var/www/LxdMosaic/ && vendor/bin/crunz schedule:run

Scheduled tasks include:

  • Collecting project and instance metrics (every 5 minutes).
  • Running scheduled backups and snapshots.
  • Enforcing backup retention policies.
  • Syncing LDAP users (hourly).
  • Taking software inventory and timer snapshots.
  • Building the search index.
  • Cleaning up expired metric and analytics history.

Post-Installation

  1. Open your browser and navigate to: https://<container_ip_address>
  2. Accept the self-signed SSL certificate warning.
  3. Follow the on-screen setup wizard to configure your initial settings:
  • Site title
  • Timezone
  • Audit logging preference
  • Strong password policy
  • Backup record retention period
  • Project analytics retention period
  • Instance metric history retention period
  1. Add your first LXD/Incus host from the dashboard.