Deployment Overview of Incus on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Debian-based operating system with root privileges. The following system components and configurations are mandatory:

• Operating System: Debian (version codename detected dynamically from /etc/os-release).
• Architecture: The system architecture is detected via dpkg --print-architecture.
• Privileges: Root access is required for installation and configuration.
• Network: IPv4 forwarding must be enabled (net.ipv4.ip_forward = 1).
• Ports: The Incus API and Web UI listen on port 8443.

File and Directory Structure¶

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

• Incus Configuration: Preseed configuration is located at /root/incus-preseed.yml.
• Incus Storage: The default storage pool is located at /var/lib/incus/storage-pools/default.
• Incus Web UI Assets: Assets are stored in /opt/incus/ui.
• Nginx Configuration:
• Directory: /root/nginx.
• Compose file: /root/nginx/compose.yml.
• User configuration: /data/nginx/user_conf.d/.
• SSL Certificates: Let's Encrypt certificates are stored in the nginx_secrets volume mounted at /etc/letsencrypt.
• Environment Variables: Nginx environment configuration is located at /data/nginx/nginx-certbot.env.

Application Installation Process¶

The installation process involves adding the Zabbly repository, installing the Incus package suite, and initializing the daemon.

1. Repository Setup:

   • The Zabbly GPG key is downloaded to /etc/apt/keyrings/zabbly.asc.
   • The stable repository is added to /etc/apt/sources.list.d/zabbly-incus-stable.sources.

2. Package Installation:

   • The following packages are installed via APT:
   • incus
   • qemu-system (required for virtual machine support)
   • incus-ui-canonical (provides the Web UI)

3. Initialization:

   • The incus daemon is initialized non-interactively using the preseed file located at /root/incus-preseed.yml.
   • The initialization command is incus admin init --preseed < /root/incus-preseed.yml.

4. Service Activation:

   • The incus.socket service is enabled and started.
   • If the socket is unavailable, the incus.service is enabled and started as a fallback.

Access Rights and Security¶

Security configurations include group management, network binding, and firewall rules managed via the proxy.

• User Groups:
• The incus-admin group is created.
• The root user is added to the incus-admin group.
• Network Binding:
• The Incus API and Web UI are configured to bind to all interfaces on port 8443 using the setting core.https_address :8443.
• Proxy Configuration:
• Nginx acts as a reverse proxy, forwarding traffic to https://127.0.0.1:8443.
• SSL termination is handled by the nginx-certbot container.

Databases¶

Incus does not utilize an external database for its core operations in this deployment. Data is stored locally within the defined storage pools.

• Storage Pool: The default storage pool named default uses the dir driver.
• Location: Data is stored in /var/lib/incus/storage-pools/default.

Docker Containers and Their Deployment¶

A Docker container is deployed to manage SSL certificates and serve as a reverse proxy for the Incus Web UI.

• Container Image: jonasal/nginx-certbot:latest.
• Deployment Method: The container is managed via docker compose.
• Compose File Location: /root/nginx/compose.yml.
• Configuration Details:
• Restart Policy: unless-stopped.
• Network Mode: host.
• Environment:
  • CERTBOT_EMAIL is set to [email protected].
  • Additional environment variables are loaded from /data/nginx/nginx-certbot.env.
• Volumes:
  • nginx_secrets (external) mounted to /etc/letsencrypt.
  • /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d.

Proxy Servers¶

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

• Proxy Target: Traffic is proxied to https://127.0.0.1:8443.
• Configuration File: The proxy rule is injected into /data/nginx/user_conf.d/{{ prefix }}{{ server_id }}.hostkey.in.conf.
• SSL Management:
• Certbot is used to obtain and renew SSL certificates.
• Certificates are stored in the nginx_secrets volume.
• Custom Domains: The configuration supports custom domains via the user_conf.d directory structure.

Permission Settings¶

File and directory permissions are set as follows:

• Preseed File: /root/incus-preseed.yml has permissions 0600 (read/write for owner only).
• Nginx Directory: /root/nginx has permissions 0755 (read/execute for all, write for owner).
• Compose File: /root/nginx/compose.yml has permissions 0644.
• Incus Storage: The storage pool directory /var/lib/incus/storage-pools/default is managed by the Incus daemon with appropriate system permissions.

Starting, Stopping, and Updating¶

The Incus daemon and the proxy container are managed using standard service commands and Docker Compose.

• Incus Service Management:
• Start/Enable: systemctl enable --now incus.socket or systemctl enable --now incus.service.
• Status Check: incus info.
• Proxy Container Management:
• Start/Update: docker compose up -d executed from the /root/nginx directory.
• Stop: docker compose down executed from the /root/nginx directory.
• Incus Configuration Updates:
• To change the bind address: incus config set core.https_address <address>:<port>.