Server on Bastien Traverse

Deploy Immich on IncusOS

Thu, 28 May 2026 00:00:00 +0200

Here are the steps I followed to set up Immich on my home server using IncusOS.

I chose to do it via Incus’ native OCI container support, instead of going through the more usual approach of spinning up a Docker host in an instance. As far as I can tell this approach hasn’t been documented anywhere yet, which makes me quite happy to be able to contribute it.

What differs in this approach

Going with Incus native OCI support means we cannot rely on docker-compose: although incus-compose is quite promising, it is not there yet for this use case. We will have to do everything manually, and that’s what this post covers.

Since it wouldn’t be fun if this was my sole “handicap”, I’m also using the immutable OS purpose-built for Incus. This means we cannot use bind mounts for the persisted data: instead we will use custom filesystem storage volumes, which on IncusOS are backed by ZFS file system datasets.

Step 1: Download and review the upstream config

The first step is to read and understand what the upstream Docker Compose setup would do.

Follow the official instructions to retrieve the files and pay attention to where and how the variables from the .env file are used in the Compose file.

Here’s the upstream .env as of writing this:

# You can find documentation for all the supported env variables at https://docs.immich.app/install/environment-variables

# The location where your uploaded files are stored
UPLOAD_LOCATION=./library

# The location where your database files are stored. Network shares are not supported for the database
DB_DATA_LOCATION=./postgres

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
# TZ=Etc/UTC

# The Immich version to use. You can pin this to a specific version like "v2.1.0"
IMMICH_VERSION=v2

# Connection secret for postgres. You should change it to a random password
# Please use only the characters `A-Za-z0-9`, without special characters or spaces
DB_PASSWORD=postgres

# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

As outlined in Immich docs, UPLOAD_LOCATION, DB_DATA_LOCATION and IMMICH_VERSION are only useful if using Docker Compose, so I commented them out.

I also uncommented and set the TZ variable and changed the DB_PASSWORD.

Since we are not using Docker Compose and its network ~~shenanigans~~ helpers, we also need to set the database and Redis HOST environment variables so that our Immich server is able to find them.

IMMICH_MACHINE_LEARNING_URL was deprecated in 2024 but still works, otherwise it can be configured in the web app settings or via the config file.

Result for me:

# You can find documentation for all the supported env variables at https://docs.immich.app/install/environment-variables

# The location where your uploaded files are stored
# not used with Incus
#UPLOAD_LOCATION=library

# The location where your database files are stored. Network shares are not supported for the database
# not used with Incus
#DB_DATA_LOCATION=postgres

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
TZ=Europe/Paris

# The Immich version to use. You can pin this to a specific version like "v2.1.0"
# not used with Incus
#IMMICH_VERSION=v2

# Connection secret for postgres. You should change it to a random password
# Please use only the characters `A-Za-z0-9`, without special characters or spaces
DB_PASSWORD=MySuperStrongPassword

# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

# Needed when not using Docker Compose
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
#DB_STORAGE_TYPE=HDD
DB_HOSTNAME=immich-postgres.incus
REDIS_HOSTNAME=immich-redis.incus
IMMICH_MACHINE_LEARNING_URL=http://immich-ml.incus:3003

Note the Incus-specific .incus TLD used: this is the default DNS domain used on managed bridges, and allows to reach instances on the same network with their hostname (which here is automatically derived from the instance name).

With the application config out of the way, let’s move to setting up the infrastructure.

Step 2: Set up a dedicated Incus project and network

This is optional, but to separate concerns I prefer to group multi-container Compose projects inside dedicated Incus projects. This way they get their own namespace which can be managed independently from other projects:

incus project create immich --config features.images=false

--config features.images=false disables images isolation, i.e. images in this project are shared with the default project.

Incus instances needs a default profile to define their root disk and default network, so we copy the default profile from the default project into our immich project:

incus profile show default | incus profile edit default --project immich

I also set up a dedicated network to better replicate what docker-compose does by default and be able to manage more easily it later on.

For reasons unknown to me, Incus managed bridged networks cannot be created outside the default project, so we have to create it there first and then the immich project use it for by default:

incus network create immich-net

incus profile device set default eth0 network=immich-net --project immich

# optionnal: restrict the project to using only this network
incus project set immich restricted.networks.access=immich-net

Before we continue, let’s switch the CLI context to this project so as to avoid having to add --project immich to every single command:

incus project switch immich

Step 3: Create the storage volumes

This will be where all our important project data will be stored. The upstream compose file uses two bind mounts and one named volume, which we replace with three custom storage volumes:

for i in postgres uploads model-cache; do
    incus storage volume create local immich_$i
done

If you are not using IncusOS, your pool will likely be named default instead of local.

Then it’s finally time to create the containers themselves!

Step 4: Create the containers

We’ll proceed in reverse order compared to how the Compose file is laid out, with the database, redis and machine-learning containers first and immich-server last.

Here’s the database container section of the official Compose file:

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      # Do not edit the next line. If you want to change the database storage location on your system, edit the value of DB_DATA_LOCATION in the .env file
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always
    healthcheck:
      disable: false

First we create the container itself with the required environment variables:

incus create \
    ghcr:immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23 \
    immich-postgres \
    -c environment.POSTGRES_PASSWORD="MySuperStrongPassword" \
    -c environment.POSTGRES_USER="postgres" \
    -c environment.POSTGRES_DB="immich" \
    -c environment.POSTGRES_INITDB_ARGS="--data-checksums"

Or, if like me you’d rather keep the environment in a separate file:

cat > .postgres-env <<EOF
POSTGRES_PASSWORD=MySuperStrongPassword
POSTGRES_USER=postgres
POSTGRES_DB=immich
POSTGRES_INITDB_ARGS=--data-checksums
EOF

incus create \
    ghcr:immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23 \
    immich-postgres \
    --environment-file .postgres-env

Warning

Do not use quotes for the values inside the env file, as it leads to double-quoting and the container will fail to start: see my bug report (update: this was fixed while I was writing this post and is awaiting a release).

Then we attach the database volume to the created container:

incus config device add immich-postgres pgdata disk \
    pool=local \
    source=immich_postgres \
    path=/var/lib/postgresql/data
# or
# incus storage volume attach local immich_postgres immich-postgres pgdata /var/lib/postgresql/data

As well as a tmpfs one to equate the shm_size: 128mb from the Compose file:

incus config device add immich-postgres shm disk \
    source=tmpfs: \
    size=128MiB \
    path=/dev/shm

Now we can launch our container and check its console output to make sure it started correctly:

incus start immich-postgres
incus console immich-postgres --show-log

I won’t repeat this last part for the next ones, but it is a good idea to check the console logs every time you start a new container (you can add --console to incus launch|start as well).

The Redis/Valkey one is the simplest, going from:

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:3b55fbaa0cd93cf0d9d961f405e4dfcc70efe325e2d84da207a0a8e6d8fde4f9
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

To:

incus launch \
    docker:valkey/valkey:9@sha256:3b55fbaa0cd93cf0d9d961f405e4dfcc70efe325e2d84da207a0a8e6d8fde4f9 \
    immich-redis

I set up the machine learning one without hardware acceleration, as IncusOS doesn’t yet provide what is required at the host level, so any GPU acceleration which requires installing something on the host is only available inside VMs with a GPU passthrough.

Without it the container setup is pretty straightforward:

# Create the container with its environment populated with the .env file content
incus create \
    ghcr:immich-app/immich-machine-learning:v2 \
    immich-ml \
    --environment-file .env

# Attach the model-cache volume
incus config device add immich-ml model-cache disk \
    pool=local \
    source=immich-model-cache \
    path=/cache

incus start immich-ml

It’s finally time for the pièce de résistance, immich-server itself. This is where we need the extra environment variables for connecting to the other containers, so if you have already added them to the .env file it is as simple as:

incus create \
    ghcr:immich-app/immich-server:v2 \
    immich-server \
    --environment-file .env

Otherwise you need to add the following to the previous command:

    -c environment.DB_HOSTNAME=immich-postgres.incus \
    -c environment.REDIS_HOSTNAME=immich-redis.incus \
    -c environment.IMMICH_MACHINE_LEARNING_URL=http://immich-ml.incus:3003

For storage we have the all so important library/uploads volume:

incus config device add immich-server uploads disk \
    pool=local \
    source=immich-uploads \
    path=/data

To replicate the exposed port form the Compose file we can use a proxy device:

incus config device add immich-server web proxy \
    listen="tcp:0.0.0.0:2283" \
    connect="tcp:127.0.0.1:2283"

This will make sure to redirect connections on the host port 2283 to the container’s.

Now we are finally ready to start it:

incus start immich-server

Check the logs to make sure everything is ok!

Tip

If you have set a different timezone in IncusOS (or on your regular OS where Incus is installed), you might want to replicate the bind mount of /etc/localtime; however liblxc prevents mounting over a symlink, and so starting the container with the host localtime mounted over the container’s one fails.

Two possible workarounds: start the container without mounting /etc/localtime, and either:

delete the file inside the container and then mount it from the host via a disk device:

# make sure the container is started
incus start immich-server

# delete the existing symlink
incus exec immich-server -- rm /etc/localtime

# mount the file from the
incus config device add immich-server localtime disk \
    source=$(realpath /etc/localtime) \
    path=/etc/localtime \
    readonly=true

overwrite the symlink inside the container with the desired timezone file:

incus exec immich-server -- ln -sf /usr/share/zoneinfo/Europe/Paris /etc/localtime

Both workarounds will need to be reapplied anytime you rebuild/update the container.

Accessing Immich

Thanks to the proxy device, it is just a matter of opening http://<server-ip>:2283 in a browser (https doesn’t work) and completing the Post-Install setup.

I was able to set up the mobile app on my phone and upload pictures right away, and it’s been running fine since then. Pretty nice!

Improvement: set a start/stop order

After restarting the server a few times, I noticed that because I didn’t set a boot.autostart.priority the containers were being started in parallel, which resulted in errors in immich-server logs showing it was waiting on the postgres one.

Therefore I configured a start and stop priority for immich-server:

incus config set immich-server boot.autostart.priority=0 boot.stop.priority=100

This benefits from the fact that “Instances without a priority set will be started (with some parallelism) ahead of instances with a priority set”, which matches exactly what we want in this case: the three supporting containers should be started before immich-server proper.

We could also set boot.autorestart to true so that immich-server gets restarted up to 10 times over a minute in case of unexpected failure.

Conclusion

I hope this will help some of you set up Immich “the hard way” on Incus/IncusOS! Let me know by email or on the forums if you have any feedback.

Optimized cloud-init templates on Proxmox

Fri, 04 Oct 2024 00:00:00 +0200

There are already quite a few resources out there demonstrating how to create a cloud-init enabled VM template in Proxmox. Here are the ones I mainly used to discover the topic, and which I suggest you go through because what follows depends on them:

Proxmox FAQ, wiki and mostly identical official documentation on Cloud-Init support
Perfect Proxmox Template with Cloud Image and Cloud Init (YouTube, Techno Tim 2022-03)

What those and many similar resources give are step-by-step instructions divided in as many commands to facilitate understanding. What I haven’t seen so far though, is an all-in-one, optimized command to do the same thing, so here’s my contribution to the field:

qm create 1000 \
    --name debian12-cloud \
    --description "Debian 12 cloud-init template" \
    --template 1 \
    --ostype l26 \
    --machine q35 \
    --cpu host \
    --cores 2 \
    --memory 4096 \
    --balloon 512 \
    --scsihw virtio-scsi-single \
    --scsi0 local-lvm:0,import-from=/path/to/debian-12-generic-amd64.qcow2,discard=on,iothread=1,ssd=1 \
    --net0 virtio,bridge=vmbr0 \
    --tablet 0 \
    --rng0 source=/dev/urandom \
    --boot order=scsi0 \
    --vga serial0 --serial0 socket \
    --ide2 local-lvm:cloudinit \
    --ciuser myuser \
    --cipassword changeme \
    --sshkey /path/to/your-public.key \
    --ciupgrade 0 \
    --ipconfig0 ip=dhcp

The same thing as a one-liner for the latest Ubuntu:

qm create 2000 --name ubuntu-server-2404-cloud --description "Ubuntu Server 24.04 cloud-init template"  --template 1 --ostype l26 --machine q35 --cpu host --cores 2 --memory 4096 --balloon 512 --scsihw virtio-scsi-single --scsi0 local-lvm:0,import-from=/path/to/ubuntu-24.04-server-cloudimg-amd64.img,discard=on,iothread=1,ssd=1 --net0 virtio,bridge=vmbr0 --rng0 source=/dev/urandom --tablet 0 --boot order=scsi0 --vga serial0 --serial0 socket --ide2 local-lvm:cloudinit --ciuser myuser --cipassword changeme --sshkey /path/to/your-public.key --ciupgrade 0 --ipconfig0 ip=dhcp

Note that you cannot copy-paste those blindly, you have to adjust a few parameters to your local environment (especially the VMID, disk image and SSH key paths).

Follows a description of relevant options at the exclusion of self-evident ones (name, description, cores, memory…), as well as some possible variations you might want.

Generic options

qm create 1000: the Proxmox CLI command to create a VM. Replace 1000 by the VMID of your choice (must be ≥ 100)
--template 1: directly convert the created VM to a template

--ostype l26: hint to optimize for a Linux 2.x-6.x-based system
--machine q35: use a modern machine type
--cpu host: pass-through the host CPU type to make all its features available in the VM
--balloon 512: when set to a lower value than memory, enables dynamic memory allocation
--scsihw virtio-scsi-single: the most performant SCSI controller, especially when combined with iothread=1 (see next point)
--scsi0 local-lvm:0,import-from=/path/to/debian-12-generic-amd64.qcow2,iothread=1,discard=on,ssd=1:
- import (i.e. copy) the referenced cloud image as the VM disk
  - replace /path/to/ with the full path to where you downloaded the cloud image (which you should have already done by now if you have followed the resources linked above 😉)
- configure it with performance (IO Thread), thin-provisioning and SSD-optimized settings
  - remove discard=on and/or ssd=1 if not applicable to your storage
--tablet 0: one of the lesser-known performance tips but one of the most important! Disables the USB tablet device only needed when connecting via the integrated console to guests with a GUI (e.g. Ubuntu Desktop). Reported to have a big performance impact.
--rng0 source=/dev/urandom (optional): provides a virtual hardware random number generator to get entropy from the host system (can speed things up during the first boot)

Up to here were performance-related options applicable to all VM templates, not only cloud-init ones. Here comes the cloud-init specific bits:

--boot order=scsi0: apparently speeds up booting for cloud-init enabled images
--vga serial0 --serial0 socket: creates the serial connection expected by most cloud images in their “native” cloud environments; also useful to monitor and troubleshoot the boot process via the Proxmox console
- verified to work with Debian 12 and Ubuntu 24.04 server cloud images; remove if causing issues with the image you’re using
--ide2 local-lvm:cloudinit: creates the required cloud-init “CD-ROM” drive
--ciuser myuser (optional): provides a custom username for the user account provisioned by cloud-init; without it the account name will depend on the distribution’s default (debian for Debian, ubuntu for Ubuntu… Check your cloud image docs about this)
--cipassword changeme (optional): generally not needed nor recommended, but useful for quickly making sure everything is all right the first few times over; afterwards use a SSH key instead
--sshkey /path/to/your-public.key (required if not setting a password): the authorized SSH public key that will be placed in the user account created by cloud-init
--ciupgrade 0 (optional): disable automatically upgrading packages during first boot; useful to speed things up during testing, afterwards remove it/set it to 1 (the default) if you want “always fresh” clones (which is probably a smart choice)
--ipconfig0 ip=dhcp: cloud-init in Proxmox doesn’t have a network configuration by default, so use this to let DHCP handle it or use something like --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1 for static config. Can be done later for each VM individually, just don’t leave it empty otherwise they won’t have any network by default.

If you already have custom cloud-init snippets, specify them via --cicustom "user=<volume>,network=<volume>,meta=<volume>", e.g. --cicustom "user=local:snippets/user-config.yaml".

If you do, make sure you have the equivalents of the Proxmox cloud-init options above set in your custom config, because using a custom user snippet overrides the complete user config set in the GUI or config! Yeah I know, it sucks and it’s not documented, boo Proxmox.

Fortunately, as mentioned in the docs the GUI config can be dumped to serve as a base for custom configs:

qm cloudinit dump 1000 user
qm cloudinit dump 1000 network

Note

Unlike Proxmox’ implementation, when using --cicustom and in the absence of network configuration, the image’s cloud-init process will generate a network configuration that will issue a DHCP request on a “first” network interface. So if DHCP is what you want, you don’t have to supply a "network:..." snippet besides the "user:..." one.

Post-creation steps

The only thing that cannot be done in the same step (due to using import-from) is resizing the disk image. I personally prefer doing it on the cloned VMs rather than on the template itself to reduce cloning time and adjust the size depending on the VM’s needs, but there is also a case to be made to do it on the template directly.

So in my case I first clone the template to a new VM:

qm clone 1000 150 --full --name "debian12-cloud"

Note

Besides being generally recommended for VMs you will keep around, it seems we can only use a full clone when using --scsihw virtio-scsi-single as without the --full option I get:

Linked clone feature is not supported for drive 'scsi0'

YMMV.

Then expand its disk size:

qm resize 150 scsi0 15G

And then we’re ready to fire up the VM!

Double-click on the VM name (or on the “Console” button at the top right) instead of going through the integrated VM-specific menu “Console” element, because the pop-up window it opens can be resized fullscreen and allows to scroll back the buffer and read the boot log if necessary.

After checking everything works, you may want to stop and destroy this test VM:

qm stop 150
qm destroy 150 --purge --destroy-unreferenced-disks 1

Now you can do the final adjustments to your template (e.g. remove --cipassword, --ciupgrade 0 etc.) and you are ready to rock the cloud-init lifestyle in Proxmox! ☁️🤘🕺

UEFI variant

Generally I try to use as modern a stack as is reasonable, because software written in the last few years is more likely to be tested with it than a more legacy stack.

But I have realized that UEFI is much less commonplace in virtualized environments than on bare metal, making it less tested and I’d say, slightly less supported overall (case in point: it’s still not the default in QEMU/Proxmox).

However it is easy enough to use it in our templates by adding the following options:

--bios ovmf --efidisk0 local-lvm:0,efitype=4m,size=4M,pre-enrolled-keys=0

The only thing to note is that pre-enrolled-keys=0 disables Secure Boot, which trips up all the distros that don’t want to play the Microsoft game (Arch Linux being a notable one for me). Leave the parameter out or switch its value to 1 for a Secure Boot-enabled template (confirmed working with Ubuntu for example)!

The QEMU Guest Agent conundrum

By default, no cloud images I know of come with qemu-guest-agent preinstalled, but it’s pretty useful on Proxmox.

To install it in your cloud images, you basically have two options:

Install and use libguestfs’ virt-customize to the cloud images themselves, as illustrated in this random blog post I found
Let cloud-init do it during the first boot of each cloned VM using a custom cloud-init snippet: see this SuperUser answer for an example. The required lines to add to your user-config.yaml are:
```
#cloud-config
...
package_update: true
packages:
  - qemu-guest-agent

runcmd:
  - systemctl enable --now qemu-guest-agent
```

Remember that using a custom user snippet overrides the complete user config set in the GUI or config, so those lines must be added to your complete user snippet!

In this case add --cicustom "user=local:snippets/user-config.yaml" and--agent 1,fstrim_cloned_disks=1 when creating the template (see the docs for details).

Tips & tricks

don’t use Debian genericcloud image: its kernel is optimized for Azure & AWS environments and in my tests, didn’t work with Proxmox. I had started with this one (being fooled by the wording on the download page ("genericcloud: Similar to generic. Should run in any virtualised environment. Is smaller than generic by excluding drivers for physical hardware"), spent quite a bit of time troubleshooting the VM booting but cloud-init not kicking in, until I eventually tried the generic image where everything worked perfectly. The Debian wiki actually sets the record straight:

The generic image uses Debian’s standard Linux kernel packages, while the genericcloud image uses the cloud kernel build. The cloud kernel disables a large number of device drivers and primarily targets the Amazon EC2 and Microsoft Azure VM device models. It may be usable in other environments, but for maximum compatibility we recommend using the generic images.

While troubleshooting I’ve seen plenty of other reports of people having issues making the genericcloud image work with Proxmox, while it worked for some others… generic is the reliable, consistant option. ’nough said!
you can get Proxmox to display .qcow2 images alongside regular .iso in its GUI, by simply suffixing/replacing their extension with .img (like Ubuntu does). It’s a regex issue ¯\_(ツ)_/¯

Remote rescue without a KVM

Mon, 08 Apr 2024 00:00:00 +0200

Context

I was looking for a way to get remote access to my laptop-turned-server even in the case the OS became unbootable (e.g. if I try to remotely encrypt the root and bork something), or more generally have a way to reinstall it from afar.

In other words, I wanted to emulate the functionalities of a KVM/cloud shell, but on consumer hardware with no remote management functionalities (e.g. vPro).

First pass

My first idea was to leave a USB drive containing a Live rescue system plugged into the laptop. The issue then becomes: how do I access the rescue environment?

One has to find either a Live system with sshd enabled by default and a default password (risky), or make/customize one so that either user-configured credentials are used (e.g. an SSH public key) or some kind of tunnel is opened automatically from the live system (I was thinking about unattended Tailnet joining, but as it sounded quite more convoluted than a simple preconfigured SSH key I didn’t explore this path further).

Searching for “live distro with ssh pre enabled” led me to two Q&A threads that proved quite useful:

Some specific Live systems were mentioned for their easy configurability:

However, I then discovered that my beloved Arch had cloud-init support baked into its regular ISO, which I am already familiar with and know to be very versatile, so I went for that.

The chosen path

As usual the Arch Wiki didn’t disappoint, offering short and practical instructions on how to use cloud-init to configure user-defined SSH keys and repacking the Live ISO so that I could burn it to my USB drive.

Tip

The “single ISO” method isn’t compatible with a default Ventoy configuration; it didn’t recognize the appended partition containing cloud-init data, and therefore it didn’t behave any different than the standard archiso. That’s why I went for burning the ISO to the drive.

After making sure I could SSH with my SSH key into the live system from the local network, I set up port redirection on the router to forward SSH requests to this machine (which I had already set up a static DHCP lease for previously).

The last and trickiest part was: how to boot on the live system only in case it’s needed?

Deciding on the boot order

Configuring the firmware to always boot from the USB drive wouldn’t work, because unlike with a proper KVM I don’t have access to the bootloader screen to choose booting from the first drive/continuing to boot normally.

I certainly can configure the next boot to use the USB drive just once by using efibootmgr -n/bootctl on the installed system, but what if the server isnt accessible anymore? Then game over, I either need a benevolent human or a domestic robot. Or, you know, pay hundreds of €€€ to fly there myself 😂

In this case this laptop-server stays at some relatives’ place, so I can rely on them to punctually press F2 to select a different boot entry.

For those who are not so lucky, I cannot think of any other parry than going with something like a Jet/PiKVM; after all, this is exactly why server motherboard/CPUs usually come with remote management features like vPro.

Conclusion

Even though it will require a third-party intervention for abnormal/rescue situations, I am pretty happy I made this solution available on my setup. It provides some easy-to-trigger reassurance. Without it it’d feel like abandoning my brave laptop-turned-server to its own device (ha!) in a chilly closet under the stairs, like an electronic Harry Potter… This way at least, I feel like I can care for it.

Graphical management interfaces for Linux servers

Mon, 11 Dec 2023 00:00:00 +0100

Terminology considerations

“Server management interface”, “control panel”, “dashboard”… While investigating Free and Open Source graphical server management software, I had trouble establishing the categorical difference between the different solutions I was reading about.

My use case being a “single user homelab/server” and not a multi-tenancy reseller/web hosting solution, I initially left aside the well established category of control panels (with the exception of HestiaCP).

The projects that caught my interest were Cockpit, HestiaCP, Portainer, CapRover, CasaOS, Cloudron, and to a lesser extent, Yacht.

But try as I might, I just couldn’t wrap my head around what precisely distinguished them. Of course I could see that they had different focus: some were more sysadmin/general server management-oriented while others were more app- and Docker-oriented; but I lacked a general category theory for them.

My search-fu not yielding anything relevant, I thought I’d probe ChatGPT about it. This resulted in a most enlightening conversation, as it answered with a distinction that felt like a Eureka moment to me:

The solutions you’ve mentioned, including Portainer, HestiaCP, CapRover, CasaOS, Cloudron, and Yacht, represent a different category of software compared to the server management tools like Cockpit, Webmin, Ajenti, and others.

It then went on to provide the following breakup:

Server Management Tools (e.g. Cockpit, Webmin, Ajenti):

Purpose:

Primarily focused on server administration and configuration.

Provide a broad range of controls over system settings, users, and services.

Complexity:

Varies from beginner-friendly to advanced, catering to users with different skill levels.

Interface Type:

Often web-based but can include desktop GUI options.

Aimed at managing servers directly, not specifically for application or container orchestration.

Scalability:

Typically suitable for small to large enterprises.

Designed for overall server management, including security, networking, and system configuration.

Community Support:

Active open-source communities provide support and contribute to feature development.

Integration:

Extensive third-party module or plugin support for customization.

May include features for managing server-wide tasks and configurations.

Application and Container Orchestration Tools (e.g. Portainer, HestiaCP, CapRover, CasaOS, Cloudron, Yacht):

Purpose:

Focused on managing and orchestrating applications, containers, and services.

Streamlined for deploying and managing web applications and services in containerized environments.

Complexity:

Typically designed to be user-friendly, catering to developers and administrators with varying skill levels.

Interface Type:

Primarily web-based interfaces, emphasizing container and application management.

Often include features for easy deployment, scaling, and monitoring of applications.

Scalability:

Suited for small to medium-scale applications and services.

Designed for ease of use in deploying and managing containerized applications.

Community Support:

Active communities, often developer-focused, providing support and contributing to the development of container-related features.

Integration:

Strong integration with containerization technologies (e.g., Docker, Kubernetes).

Emphasis on managing application stacks, updating applications, and maintaining service availability.

Note that:

the content of some categories don’t really fit their header (e.g. “Interface Type”)
HestiaCP is lumped in the “Application and Container Orchestration Tools” category, despite its features being arguably more control panel-y/towards server management.

This is to just highlight the very reasonable limits of ChatGPT (3.5), in what was otherwise a super useful answer.

Coming up with a unified categorization

I kept poking at the prompt until I managed to formulate a General Category Theory of Server Management Graphical User Interfaces™, inclusive of control panels and mere dashboards. Here’s the result:

The terms “server management tools”, “control panels”, “application and container orchestration tools” and “server dashboards” are sometimes used interchangeably, but they often refer to different aspects of managing and monitoring servers. Here’s how you can distinguish between them:

Server Management Tools:

Purpose: Server management tools are software applications designed to facilitate the configuration, administration, and monitoring of servers. They offer a range of features for tasks such as user management, service configuration, and system monitoring.

Scope: Server management tools encompass a broad set of functionalities related to overall server administration, configuration, and maintenance.

Examples: Cockpit, Webmin, Ajenti and ISPConfig are examples of server management tools.

Control Panels:

Purpose: Control panels are specialized interfaces that provide centralized control over specific server functionalities, often in a web-based environment. They are designed to simplify the management of specific server aspects, such as web hosting, email services, or database management.

Scope: Control panels are more focused and may not cover all aspects of server management. They often excel in specific use cases and are user-friendly for individuals who may not have extensive server administration experience.

Examples: HestiaCP, Froxlor and Virtualmin are examples of control panels.

Application and Container Orchestration Tools:

Purpose: These tools aim to streamline application deployment, scale applications automatically to handle varying workloads, provide centralized management for containers, and automate various aspects of deployment and updates, ultimately enhancing overall efficiency.

Scope: Their scope includes container orchestration, service discovery, load balancing, health monitoring, and automated rollbacks and updates. They focus on managing and coordinating the deployment, scaling, and operation of application containers in a containerized environment, ensuring seamless and efficient operations.

Examples: Portainer, CapRover and Yacht are examples of application and container orchestration tools.

Server Dashboards:

Purpose: Server dashboards are visual representations of real-time or historical server data, allowing users to monitor key metrics and performance indicators. They provide a quick overview of the server’s health and status.

Scope: Dashboards are primarily focused on providing visibility into server performance metrics and may not offer the same depth of configuration and administration features as management tools or control panels.

Examples: Grafana, Kibana, and custom dashboards created using tools like Prometheus or Nagios are examples of server dashboards.

In summary, while there is some overlap in functionality, server management tools generally provide a comprehensive set of features for overall server administration. Control panels are more specialized, focusing on specific server functionalities. Application and container orchestration tools are geared towards managing and orchestrating applications and containers, ensuring efficient deployment, scaling, and maintenance. Server dashboards, on the other hand, offer visual representations of server performance metrics for monitoring purposes. The choice between them depends on the specific needs and preferences of the user or organization.

So, even though ChatGPT kind of threw my FOSS requirement to the wind by mentioning famous proprietary panels (that I replaced here), all in all I feel like we did a great job coming up with a good typology of graphical, general purpose GNU/Linux server management solutions (what a mouthful 😅).

Category members

Now that our categories are well defined, it is time to flesh them out by filling them with our candidates!

Without further ado, here’s a curated list with stuff somewhat beyond my initial use case:

Server Management Tools:

Cockpit Project
- License: LGPL 2.1
- Purpose: Web-based server administration and monitoring.
- Complexity: Beginner to Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for both SMEs and large enterprises.
- Community Support: Growing community.
- Integration: Focus on integration with systemd and containers.
- GitHub Repository
Webmin
- License: BSD
- Purpose: Comprehensive web-based server configuration and management.
- Complexity: Varies from beginner-friendly to advanced.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs and large enterprises.
- Community Support: Active community.
- Integration: Extensive third-party module support.
- GitHub Repository
Ajenti
- License: AGPLv3
- Purpose: Web-based server administration with support for plugins.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Supports various plugins for extended functionality.
- GitHub Repository
ISPConfig
- License: BSD
- Purpose: All-in-one server management panel.
- Complexity: Intermediate to Advanced.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs and large enterprises.
- Community Support: Active community.
- Integration: Strong support for multi-server setups.
- GitHub Repository
Zentyal
- License: GPLv2
- Purpose: Linux Small Business Server.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Offers a wide range of server modules.
- GitHub Repository

Web hosting/Control Panels

HestiaCP
- License: GPLv3
- Purpose: Web hosting control panel.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Manages website hosting, email services, and server configurations.
- GitHub Repository
Froxlor
- License: GPL
- Purpose: Server management panel with a focus on web hosting and server administration.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Manages web hosting, domain configurations, and server settings.
- GitHub Repository
Virtualmin
- License: GPL
- Purpose: Web hosting control panel with a focus on managing virtual hosts.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Manages website hosting, email services, and server configurations.
- GitHub Repository (Note: Virtualmin is primarily available through its official website, and its source code is available on GitHub for specific components.)
CyberPanel
- License: GPL
- Purpose: Web hosting control panel with a focus on performance and security.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Manages website hosting, email services, and server configurations.
- GitHub Repository (Note: CyberPanel is primarily available through its official website, and its source code is available on GitHub.)
AlternC
- License: GPLv3
- Purpose: Web hosting control panel with a focus on environmental responsibility.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- GitHub Repository

Application/Container Orchestration Tools:

Portainer
- License: AGPLv3
- Purpose: Docker container management.
- Complexity: Beginner to Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Manages Docker containers with a user-friendly interface.
- GitHub Repository
CapRover
- License: Apache License 2.0
- Purpose: Automated deployment for web apps.
- Complexity: Beginner to Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Focus on automated deployment of web applications.
- GitHub Repository
CasaOS
- License: AGPLv3
- Purpose: Server management and automation.
- Complexity: Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Provides server management and automation features.
- GitHub Repository
Cloudron
- License: Proprietary
- Purpose: Self-hosted web app platform.
- Complexity: Beginner to Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Manages self-hosted web applications.
- GitHub Repository
Yacht
- License: MIT
- Purpose: Docker management with a focus on simplicity.
- Complexity: Beginner to Intermediate.
- Interface Type: Web-based.
- Scalability: Suitable for SMEs.
- Community Support: Active community.
- Integration: Simplifies Docker container management.
- GitHub Repository

Now it’s experimentation time! 🥳

PS: If you need even more, here is a random article listing 30 similar solutions including many dashboards.

Happy hacking!

Server on Bastien Traverse

Deploy Immich on IncusOS

What differs in this approach

Step 1: Download and review the upstream config

Step 2: Set up a dedicated Incus project and network

Step 3: Create the storage volumes

Step 4: Create the containers

Accessing Immich

Improvement: set a start/stop order

Conclusion

Optimized cloud-init templates on Proxmox

Generic options

Performance related options

Cloud-init related options

Post-creation steps

UEFI variant

The QEMU Guest Agent conundrum

Tips & tricks

Remote rescue without a KVM

Context

First pass

The chosen path

Deciding on the boot order

Conclusion

Graphical management interfaces for Linux servers

Terminology considerations

Coming up with a unified categorization

Category members

Server Management Tools:

Web hosting/Control Panels

Application/Container Orchestration Tools: