Homeserver

Warning

Use at your own risk! This is a work in progress with heavy testing happening in the master branch. This image is intended to use ucore-minimal as it's source; do not expect it to work with any other source images!

My custom uCore homeserver image generated by the ublue-os/image_template. Intended for my own personal use.

Special thanks to bketelsen for inspiring and solving a lot of the little issues I ran into!

Image Details

Image Modifications

Installed Applications

In addition to default ucore-minimal applications and services. The following modifications have been included in homeserver.

• lxc/incus is a modern, secure and powerful system container and virtual machine manager.

• bketelsen/inventory is an application that tracks deployed services/containers. It was built with a homelab in mind.

Configuration Tips & Tricks

incus

Tip

Initialize Incus and configure System Firewall

• Run incus admin init or incus admin init --minimal to initialize. https://linuxcontainers.org/incus/docs/main/howto/initialize/
• Add default incus bridge to the firewall (change the interface name to the name you chose):

  sudo firewall-cmd --zone=trusted --change-interface=incusbr0 --permanent
  sudo firewall-cmd --reload
  

---

inventory

Tip

The inventory server is configured to run on port 8000 and receive rpc from client on port 9999. Configure System Firewall to allow port 8000 (and 9999 if external services are reporting in).

• Add inventory-server to the firewall:

  sudo firewall-cmd --zone=FedoraServer --add-port=8000/tcp --permanent
  sudo firewall-cmd --reload
  

• Only enable port 9999 if you have external inventory clients reporting to this server!

  sudo firewall-cmd --zone=FedoraServer --add-port=9999/tcp --permanent
  sudo firewall-cmd --reload
  

---

tailscale

Tip

Tailscale is configured to be enabled by default in this image. Disable if you wont be using or configure it if you will be using.

• Run sudo tailscale up --operator=$USER to configure tailscale.
• Run sudo systemctl disable tailscaled.service to disable the service.

---

Source Image Details

The source image for homeserver is ublue-os/ucore-minimal:stable-nvidia-zfs. Details from the uCore readme provided below.

fedora-coreos

Important

This was previously named fedora-coreos-zfs, but that version of the image did not offer the nvidia option. If on the previous image name, please rebase with rpm-ostree rebase.

A generic Fedora CoreOS image image with choice of add-on kernel modules:

• nvidia versions add:
  • nvidia driver - latest driver built from negativo17's akmod package
  • nvidia-container-toolkit - latest toolkit which supports both root and rootless podman containers and CDI
  • nvidia container selinux policy - allows using --security-opt label=type:nvidia_container_t for some jobs (some will still need --security-opt label=disable as suggested by nvidia)
• ZFS versions add:
  • ZFS driver - latest driver (currently pinned to 2.2.x series)

Note

zincati fails to start on all systems with OCI based deployments (like uCore). Upstream efforts are active to develop an alternative.

ucore-minimal

Suitable for running containerized workloads on either bare metal or virtual machines, this image tries to stay lightweight but functional.

• Starts with a Fedora CoreOS image
• Adds the following:
  • bootc (new way to update container native systems)
  • cockpit (podman container and system management)
    • Configured to run on port 9090
  • firewalld
  • guest VM agents (qemu-guest-agent and open-vm-tools))
  • docker-buildx and docker-compose (versions matched to moby release) docker(moby-engine) is pre-installed in CoreOS
  • podman-compose podman is pre-installed in CoreOS
  • tailscale and wireguard-tools
  • tmux
  • udev rules enabling full functionality on some Realtek 2.5Gbit USB Ethernet devices
• Optional nvidia versions add:
  • nvidia driver - latest driver built from negativo17's akmod package
  • nvidia-container-toolkit - latest toolkit which supports both root and rootless podman containers and CDI
  • nvidia container selinux policy - allows using --security-opt label=type:nvidia_container_t for some jobs (some will still need --security-opt label=disable as suggested by nvidia)
• Optional ZFS versions add:
  • ZFS driver - latest driver (currently pinned to 2.2.x series) - see below for details
  • pv is installed with zfs as a complementary tool
• Disables Zincati auto upgrade/reboot service
• Enables staging of automatic system updates via rpm-ostreed
• Enables password based SSH auth (required for locally running cockpit web interface)
• Provides public key allowing SecureBoot (for ucore signed nvidia or zfs drivers)

Important

Per cockpit's instructions the cockpit-ws RPM is not installed, rather it is provided as a pre-defined systemd service which runs a podman container.

Installation

Important

Read the CoreOS installation guide before attempting installation. uCore extends Fedora CoreOS; it does not provide it's own custom or GUI installer.

There are varying methods of installation for bare metal, cloud providers, and virtualization platforms.

All CoreOS installation methods require the user to produce an Ignition file. This Ignition file should, at mimimum, set a password and SSH key for the default user (default username is core).

Tip

For bare metal installs, first test your ignition configuration by installing in a VM (or other test hardware) using the bare metal process.

Image Verification

These images are signed with sigstore's cosign. You can verify the signature by running the following command:

cosign verify --key https://github.com/chris-neely/homeserver/blob/main/cosign.pub ghcr.io/chris-neely/homeserver:TAG

Auto-Rebase Install

One of the fastest paths to running uCore is using examples/ucore-autorebase.butane as a template for your CoreOS butane file.

Tip

You will need to update this example with the REPO name, IMAGE, and TAG if you're going to use homeserver.

1. As usual, you'll need to follow the docs to setup a password. Substitute your password hash for YOUR_GOOD_PASSWORD_HASH_HERE in the ucore-autorebase.butane file, and add your ssh pub key while you are at it.
2. Generate an ignition file from your new ucore-autorebase.butane using the butane utility.
3. Now install CoreOS for hypervisor, cloud provider or bare-metal, i.e. sudo coreos-installer install /dev/nvme0n1 --ignition-url https://example.com/ucore-autorebase.ign (or --ignition-file /path/to/ucore-autorebase.ign). Your ignition file should work for any platform, auto-rebasing to the ucore:stable (or other IMAGE:TAG combo), rebooting and leaving your install ready to use.

Manual Install/Rebase

Once a machine is running any Fedora CoreOS version, you can easily rebase to uCore. Installing CoreOS itself can be done through a number of provisioning methods.

Warning

Rebasing from Fedora IoT or Atomic Desktops is not supported! If ignition doesn't provide a desired feature, then Fedora CoreOS doesn't support that feature. Rebasing from another system to gain a filesystem feature or GUI installation is very likely to cause problems later on.

To rebase an existing CoreOS machine to the latest uCore:

1. Execute the rpm-ostree rebase command (below) with desired IMAGE and TAG.
2. Reboot, as instructed.
3. After rebooting, you should pin the working deployment which allows you to rollback if required.

sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/chris-neely/homeserver:TAG

Verified Image Updates

The ucore* images include container policies to support image verification for improved trust of upgrades. Once running one of the ucore* images, the following command will rebase to the verified image reference:

sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/chris-neely/homeserver:TAG

Note

This policy is not included with fedora-coreos:* as those images are kept very stock.*