Deployment Overview of Incus on Server¶

Prerequisites and Basic Requirements¶

The deployment of the Incus containerization and virtualization platform requires a Debian-based operating system. The installation process utilizes the APT package manager and relies on specific system configurations to function correctly.

Operating System: Debian-based distribution (Debian codename required for repository configuration).
Privileges: Root access or equivalent sudo privileges are required to install packages, configure system services, and modify network settings.
System Packages: The following base tools are required or installed during setup:
ca-certificates
gnupg
incus
qemu-system (required for virtual machine support)
incus-ui-canonical (Web UI component)
Network Configuration: IPv4 forwarding must be enabled on the host system (net.ipv4.ip_forward set to 1).

FQDN of the Final Panel¶

The application is accessible via a specific Fully Qualified Domain Name (FQDN) hosted on the hostkey.in domain. The URL follows a specific pattern based on the server identifier.

Domain Pattern: incus<Server ID>.hostkey.in
Full Access URL: https://incus<Server ID>.hostkey.in/
External Port: 443 (HTTPS)

File and Directory Structure¶

The Incus installation and associated proxy services utilize specific directories for configuration, data storage, and user certificates.

Incus Storage Pool: /var/lib/incus/storage-pools/default
Incus Preseed Configuration: /root/incus-preseed.yml
Web UI Assets: /opt/incus/ui
Nginx and Proxy Configuration:
Docker Compose file: /root/nginx/compose.yml
Nginx user configuration: /data/nginx/user_conf.d/
Nginx environment file: /data/nginx/nginx-certbot.env
Nginx secrets directory: /etc/letsencrypt (mounted from nginx_secrets volume)

Application Installation Process¶

The Incus application is installed using the APT package manager from the Zabbly repository. The process involves adding the repository key, configuring the source list, and installing the core components.

Repository Setup:
The Zabbly repository key is retrieved and stored in /etc/apt/keyrings/zabbly.asc.
The repository configuration is added to /etc/apt/sources.list.d/zabbly-incus-stable.sources.
Package Installation:
The incus package provides the daemon and CLI.
The qemu-system package enables virtual machine capabilities.
The incus-ui-canonical package provides the web interface assets.
Initialization:
Incus is initialized non-interactively using a preseed file located at /root/incus-preseed.yml.
The initialization creates a network bridge named incusbr0 and a storage pool named default using the dir driver.
A profile named default is created to attach the root disk and bridge network device to instances.

Access Rights and Security¶

Security is enforced through system groups, network binding restrictions, and firewall rules managed by the proxy layer.

User Groups:
A system group named incus-admin is created.
The root user is added to the incus-admin group to manage Incus instances.
Network Binding:
The Incus API and UI are configured to bind to all network interfaces on port 8443 (core.https_address set to :8443).
Services:
The incus.socket or incus.service is enabled and started via systemd.
Proxy Security:
An external Nginx container handles SSL termination and exposes port 443 to the public internet.
The Nginx configuration proxies requests to the internal Incus service.

Docker Containers and Their Deployment¶

A Docker container is deployed to manage reverse proxying and SSL certificate generation using Certbot.

Container Image: jonasal/nginx-certbot:latest
Deployment Method: docker compose
Configuration File: /root/nginx/compose.yml
Service Details:
The service runs with network_mode: host.
It uses the nginx_secrets volume to store Let's Encrypt certificates in /etc/letsencrypt.
The user configuration directory /data/nginx/user_conf.d is mounted to /etc/nginx/user_conf.d inside the container.
The service is configured with restart: unless-stopped.

Proxy Servers¶

Access to the Incus Web UI is provided through an Nginx reverse proxy container that handles SSL termination and domain routing.

Proxy Server: Nginx (running in a Docker container).
SSL/Certificates: Managed by Certbot, storing certificates in the nginx_secrets volume.
Domain Configuration:
The Nginx configuration file is located at /data/nginx/user_conf.d/incus<Server ID>.hostkey.in.conf.
The proxy rule directs traffic from the root path (/) to the internal Incus instance.
Proxy Pass Directive: proxy_pass https://127.0.0.1:8443;
External Port: 443 (HTTPS).

Available Ports for Connection¶

The system exposes specific ports for internal service management and external user access.

Port	Protocol	Description	Access
443	TCP	HTTPS (External Access via Nginx Proxy)	Public (External)
8443	TCP	Incus API and Web UI (Internal)	Internal (127.0.0.1 or host interface)

Starting, Stopping, and Updating¶

Service management for the core Incus daemon and the proxy container is handled via systemd and docker compose respectively.

Incus Service Management:
The Incus service is managed as a systemd unit.
To ensure the service is running and enabled at boot, the incus.socket or incus.service unit is started.
Proxy Container Management:
The Nginx proxy container is started and managed using Docker Compose from the /root/nginx directory.

Command to start/restart the proxy:

docker compose -f /root/nginx/compose.yml up -d

Incus Configuration Updates:
Network bindings are configured using the Incus CLI:
```
incus config set core.https_address :8443
```
Instance and project management is performed via the standard incus command-line tool.