[Tutorial] Installing the Web UI for Incus on Fedora or other Redhat-based distros

Incus
1

If you’re on Fedora or another Redhat based system and you’re using Incus, you’ve probably installed it from _copr:copr.fedorainfracloud.org:ganto:lxc4.repo or built it from source. Since there aren’t any rpm packages for the Web UI for Incus your only options are to try and install it from source (which is complicated because it’s based on lxd-ui) or to shoehorn it in manually. Lucking shoehorning it in is fairly easy…

  • First visit GitHub - zabbly/incus: Incus package repository since that’s the home of incus-ui. You don’t need to follow any of the instructions there though. Give the repo a star while you’re there.
  • Since we can’t actually install the referenced incus-ui-canonical package, we’ll need to download it directly from from Index of /incus/stable/pool/main/i/incus/. Download the latest incus-ui-canonical .deb file. The ubuntu release and architecture don’t matter because there are no executable files in the package.
  • Using either dnf or yum as appropriate, install the dpkg package if you don’t already have it. If you’re not on Fedora, you may have to install the “Extra Packages for Enterprise Linux” epel-release package first.
  • Change to the directory you downloaded the .deb file to and extract it with dpkg -x <deb file name> ./incus-ui/.
  • Copy the incus-ui/opt/incus directory to /opt/incus
    sudo rsync -vaH incus-ui/opt/incus/. /opt/incus/
  • Now enable the incus API server… sudo incus config set core.https_address :8443
    You can use any port you want but 8443 is what is used in most of the documentation.
  • The incus package at GitHub - zabbly/incus: Incus package repository tells incusd where the UI is with an environment variable but the incus package from copr.fedorainfracloud.org:ganto:lxc4 doesn’t so we have to tweak that a bit. As root…
    • Create the directory /etc/systemd/system/incus.service.d
    • Create a file named 10-env.conf in that directory with the following contents…
    [Service]
Environment=INCUS_UI=/opt/incus/ui/
    • Run…
    systemctl daemon-reload
systemctl restart incus
  • Visit https://localhost:8443 and accept the risk from the untrusted cert. If you have a server certificate you’d like to use instead of the default untrusted one, simply copy the certificate and key into /var/lib/incus as server.crt and server.key respectively and restart incus. If you’re using a Letsencrypt cert, copy fullchain.pem not cert.pem to server.crt.

That wasn’t to bad. Unfortunately, now you’re going to run into a problem. The default authentication mechanism for the UI is client certificates and when you visit https://localhost:8443 for the first time, you’ll be prompted to create a new client certificate which you’ll then have to import into your browser. Unfortunately, importing PKCS12 certificates is broken in many current browsers and distributions. To get around that, head on over to Configure Incus UI with SSO to set up Google SSO. There’s another page which may be easier to follow at Setup oidc login · canonical/lxd-ui Wiki · GitHub that also describes how to set it up.

That should do it.

2 Likes
2

@gtjoseph thank you for this, I use Fedora Sway Spin and this helped allot!

I was able to handle the certificate authentication by skipping the UI method and generating the key(s) using OpenSSL via cli (shown below).

cd ~/.config/incus
openssl genpkey -algorithm RSA -out incus-ui.key
openssl req -new -key incus-ui.key -out incus-ui.csr
openssl x509 -req -days 365 -in incus-ui.csr -signkey incus-ui.key -out incus-ui.crt
openssl pkcs12 -export -out incus-ui.p12 -inkey incus-ui.key -in incus-ui.crt
incus config trust add-certificate ~/.config/incus/incus-ui.crt

The certificates can be stored wherever you prefer, adjust the file paths as needed.

Import the incus-ui.ps12 file into your browser of choice and restart.

3

Which browser do you use? It was the importing that always failed for me.

4

This is the OS I am using - Fedora Linux 40 (Sway) x86_64 - I am using the stock Firefox that was installed with this Spin.

When I used LXD-UI to generate the keys, it failed as well. However, when I generated the keys myself everything worked.