Deployment Overview of Incus on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the following requirements must be met:

• Operating System: Debian-based distribution.

• Privileges: Root or sudo access is required for package installation and system configuration.

• Network Configuration:

• IPv4 forwarding must be enabled (net.ipv4.ip_forward = 1).

• A bridge network named incusbr0 is created during initialization.

• Ports:

• 8443: Internal API and Web UI port (HTTPS).

• 443: External HTTPS access via Nginx proxy.

FQDN of the final panel on the hostkey.in domain¶

The application uses a specific domain template for accessing the management interface:

File and Directory Structure¶

The following directories are used for configuration, data, and certificates:

• /etc/apt/keyrings/: Contains the Zabbly repository GPG key.

• /etc/apt/sources.list.d/zabbly-incus-stable.sources: Repository source file for Incus.

• /root/nginx/: Contains the Nginx Docker Compose configuration.

• /root/incus-preseed.yml: Configuration file used for non-interactive Incus initialization.

• /data/nginx/user_conf.d/: Stores Nginx virtual host configurations and proxy settings.

• /data/nginx/nginx-certbot.env: Environment variables for the Certbot container.

• /var/lib/incus/storage-pools/default: Default storage pool location.

Application installation process¶

The installation follows a multi-step process involving package management and automated configuration:

1. Repository Setup: The Zabbly repository key is added to /etc/apt/keyrings/, and the stable Incus repository is configured for the specific Debian codename and system architecture.

2. Package Installation: The following packages are installed via apt:

3. incus

4. qemu-system (for Virtual Machine support)

5. incus-ui-canonical (Web UI assets)

6. System Configuration:

7. An incus-admin group is created, and the root user is added to this group.

8. IPv4 forwarding is enabled via sysctl.

9. Incus Initialization: The application is initialized non-interactively using a preseed file (/root/incus-preseed.yml). This configures:

10. A bridge network named incusbr0 with automatic IPv4 addressing.

11. A default storage pool named default located at /var/lib/incus/storage-pools/default.

12. A default profile for containers including a root disk and the eth0 network interface.

13. Web UI Configuration: The Incus API and Web UI are bound to port 8443 on all interfaces to allow proxy access.

Access Rights and Security¶

• User Management: An incus-admin group is established for administrative tasks.

• Firewall/Network: IPv4 forwarding is enabled to facilitate container networking via the incusbr0 bridge.

• Service Security: The Incus API is secured via HTTPS on port 8443.

Docker Containers and Their Deployment¶

The deployment utilizes a Docker container to handle SSL termination and reverse proxying:

Nginx Certbot Container

• Image: jonasal/nginx-certbot:latest

• Ports: Uses network_mode: host to bind directly to system ports.

• Volumes:

• nginx_secrets:/etc/letsencrypt (External volume for SSL certificates)

• /data/nginx/user_conf.d:/etc/nginx/user_conf.d (User configuration directory)

• Environment Variables:

• [email protected]

• Restart Policy: unless-stopped

Custom Scripts and Additional Setup¶

The deployment performs several automated setup actions:

• Automated Initialization: A preseed script (/root/incus-preseed.yml) is used to automate the initial configuration of networks, storage pools, and profiles.

• Proxy Configuration: The installation automatically modifies Nginx configuration files in /data/nginx/user_conf.d/ to include a proxy_pass directive pointing to https://127.0.0.1:8443.

Application Update Instructions¶

To update the main application, use the system package manager:

apt update && apt upgrade incus

If using Docker for the proxy component, you can update the Nginx container by navigating to the configuration directory and running:

cd /root/nginx
docker compose pull && docker compose up -d

Location of configuration files and data¶

• Incus Configuration: Managed via incus config commands.

• Nginx User Configs: /data/nginx/user_conf.d/

• Docker Compose File: /root/nginx/compose.yml

• Storage Data: /var/lib/incus/storage-pools/default

Available ports for connection¶

Starting and Stopping the application¶

The Incus service can be managed via systemctl:

• Start Incus: systemctl start incus.service (or incus.socket)

• Stop Incus: systemctl stop incus.service

• Enable on Boot: systemctl enable incus.service

Proxy Servers¶

The system uses an Nginx container with Certbot integration to provide SSL termination. It acts as a reverse proxy, forwarding HTTPS traffic from the standard port 443 to the Incus Web UI running locally on port 8443.