Deployment Overview of Incus on Server¶

Prerequisites and Basic Requirements¶

The following requirements must be met on the target server before or during the deployment process:

• Operating System: Debian-based distribution (verified via /etc/os-release).

• Privileges: Root access is required for installation and configuration.

• Network: IPv4 forwarding must be enabled (net.ipv4.ip_forward).

• Ports:

• Internal: 8443 (Incus API and Web UI).

• External: 443 (HTTPS traffic via Nginx proxy).

FQDN of the Final Panel¶

The application is accessible via the following Fully Qualified Domain Name (FQDN) format:

• incus<Server ID>.hostkey.in

• The service is served over HTTPS on port 443.

• The full URL format is: https://incus<Server ID>.hostkey.in/

File and Directory Structure¶

The deployment utilizes the following directory structure for configuration, data, and certificates:

• /etc/apt/keyrings/: Stores the Zabbly repository GPG key (zabbly.asc).

• /etc/apt/sources.list.d/: Contains the Zabbly Incus stable repository configuration (zabbly-incus-stable.sources).

• /root/:

• incus-preseed.yml: Pre-seed configuration file for Incus initialization.

• nginx/: Directory containing the Docker Compose configuration for the proxy.

• /var/lib/incus/: Default storage location for Incus instances and images.

• /opt/incus/ui/: Location of the Incus Web UI assets (provided by incus-ui-canonical).

• /data/nginx/:

• user_conf.d/: Contains custom Nginx configuration files for the specific domain.

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

• nginx_secrets: Volume mount point for Let's Encrypt certificates.

Application Installation Process¶

The Incus application is installed using the APT package manager from the Zabbly repository. The process includes the following steps:

1. Repository Setup:

   • The Zabbly GPG key is added to /etc/apt/keyrings/zabbly.asc.

   • The stable repository is configured in /etc/apt/sources.list.d/zabbly-incus-stable.sources.

2. Package Installation:

   • The following packages are installed:

   • incus: Core container and virtual machine management.

   • qemu-system: Required for running virtual machines.

   • incus-ui-canonical: Provides the web-based user interface.

3. Initialization:

   • Incus is initialized non-interactively using the pre-seed file located at /root/incus-preseed.yml.

   • The initialization creates a default network bridge (incusbr0) and a default storage pool (default).

Access Rights and Security¶

Security and access control are configured as follows:

• User Groups:

• The incus-admin group is created.

• The root user is added to the incus-admin group to manage Incus.

• Network Security:

• IPv4 forwarding is enabled at the kernel level.

• The Incus API and UI are bound to 127.0.0.1:8443 initially, then exposed to all interfaces on port 8443 for internal proxying.

• Firewall:

• External access is restricted to port 443 (HTTPS) via the Nginx proxy.

• Direct access to port 8443 is not exposed to the public internet.

Databases¶

• No external database services are configured or required for the Incus application itself.

• Incus stores its internal state and configuration in its local storage pool located at /var/lib/incus.

Docker Containers and Their Deployment¶

A Docker container is deployed to handle reverse proxying and SSL certificate management.

• Container Image: jonasal/nginx-certbot:latest

• Deployment Method: Docker Compose

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

• Configuration Details:

• Restart Policy: unless-stopped

• Network Mode: host

• Volumes:

  • nginx_secrets (external) mounted to /etc/letsencrypt for certificate storage.

  • /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d for custom configurations.

• Environment:

  • CERTBOT_EMAIL: Set to [email protected].

  • Additional environment variables are loaded from /data/nginx/nginx-certbot.env.

Proxy Servers¶

Nginx is utilized as a reverse proxy to handle SSL termination and route traffic to the Incus Web UI.

• Proxy Configuration:

• The Nginx container listens on port 443 (HTTPS).

• Traffic is proxied to the Incus service running on https://127.0.0.1:8443.

• SSL/TLS:

• Managed automatically by the nginx-certbot container.

• Certificates are stored in the nginx_secrets volume.

• Custom Domain:

• The proxy is configured for the domain incus<Server ID>.hostkey.in.

• The configuration file is located at /data/nginx/user_conf.d/incus<Server ID>.hostkey.in.conf.

• The proxy_pass directive is set to https://127.0.0.1:8443.

Permission Settings¶

File and directory permissions are set as follows:

• /etc/apt/keyrings/: Mode 0755.

• /etc/apt/sources.list.d/zabbly-incus-stable.sources: Mode 0644.

• /root/incus-preseed.yml: Mode 0600, owned by root:root.

• /root/nginx/: Mode 0755, owned by root:root.

• /root/nginx/compose.yml: Mode 0644, owned by root:root.

• /data/nginx/user_conf.d/: Mode 0755 (inferred from standard Nginx config practices and volume mount).

Location of Configuration Files and Data¶

Key configuration files and data locations include:

• Incus Pre-seed: /root/incus-preseed.yml

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

• Incus UI Assets: /opt/incus/ui/

• Nginx Compose: /root/nginx/compose.yml

• Nginx Custom Config: /data/nginx/user_conf.d/incus<Server ID>.hostkey.in.conf

• Nginx Environment: /data/nginx/nginx-certbot.env

Available Ports for Connection¶

The following ports are utilized by the deployed services:

• Port 443: HTTPS (External access via Nginx proxy).

• Port 8443: HTTPS (Internal access to Incus API and Web UI).

Starting, Stopping, and Updating¶

Service management is handled via systemd for Incus and docker compose for the proxy.

Incus Service Management:

• Start/Enable:

  systemctl start incus.socket
  systemctl enable incus.socket
  

  Note: If incus.socket is not present, the fallback service is incus.service.

• Check Status:

  incus info
  

Nginx Proxy Management:

• Start/Restart:

  cd /root/nginx
  docker compose up -d
  

• Stop:

  cd /root/nginx
  docker compose down
  

Updating:

• To update Incus packages:

  apt update
  apt upgrade incus qemu-system incus-ui-canonical
  

• To update the Nginx container image:

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