uCore

What is this?

You should be familiar with Fedora CoreOS, as this is an OCI image of CoreOS with "batteries included". More specifically, it's an opinionated, custom CoreOS image, built daily with some commonly used tools added in. The idea is to make a lightweight server image including most used services or the building blocks to host them.

WARNING: This image has not been heavily tested, though the underlying components have. Please take a look at the included modifications and help test if this project interests you.

Features

ucore images:

• Start with a Fedora CoreOS image
• Remove stock packages:
  • toolbox
• Add the following:
  • cockpit
  • distrobox
  • duperemove
  • moby-engine(docker), docker-compose and podman-compose
  • tailscale and wireguard-tools
  • ZFS
• Enable staging of automatic system updates via rpm-ostreed
• Disable Zincati auto upgrade/reboot service
• Set a 60 second service stop timeout for reasonably fast shutdowns
• Enable password based SSH auth (required for locally running cockpit web interface)
• Suitable for use on bare metal or virtual machines to run containerized workloads

ucore-hci images:

• Start with ucore to give you everything above, PLUS:
• Add the following:
  • libvirt-daemon-kvm: KVM hypervisor management
  • virt-install: command-line utility for installing virtual machines
  • libvirt-client: virsh command-line utility for managing virtual machines
  • cockpit-machines: Cockpit GUI for managing virtual machines
• Suitable for use on bare metal to run as a hypervisor in addition to running containerized workloads

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

Tips and Tricks

Immutability and Podman

These images are immutable, you can't, and really shouldn't, install packages like in a mutable "normal" distribution.

CoreOS expects the user to run services using podman. moby-engine, the free Docker implementation, is installed for those who desire docker instead of podman.

Default Services

To maintain this image's suitability as a minimal container host, most add-on services are not auto-enabled.

To activate any of the pre-installed cockpit, docker, libvirtd, tailscaled services, etc:

sudo systemctl enable --now SERVICENAME.service

Docker/Moby and Podman

NOTE: CoreOS cautions against running podman and docker containers at the same time. Thus, docker.socket is disabled by default to prevent accidental activation of the docker daemon, given podman is the default.

Distrobox

Users may use distrobox to run images of mutable distributions where applications can be installed with traditional package managers. This may be useful for installing interactive utilities such has htop, nmap, etc. As stated above, however, services should run as containers.

CoreOS and ostree Docs

It's a good idea to become familar with the Fedora CoreOS Documentation as well as the CoreOS rpm-ostree docs. Note especially, this image is only possible due to ostree native containers.

ZFS

The ZFS kernel module and tools are pre-installed, but like other services, ZFS is not pre-configured to load on default.

Load it with the command modprobe zfs and use zfs and zpool commands as desired.

Per the OpenZFS Fedora documentation:

By default ZFS kernel modules are loaded upon detecting a pool. To always load the modules at boot:

echo zfs > /etc/modules-load.d/zfs.conf

How to Install

Prerequsites

This image is not currently available for direct install. The user must follow the CoreOS installation guide. 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).

Install and Manually Rebase

You can rebase any Fedora CoreOS x86_64 installation to uCore. Installing CoreOS itself can be done through a number of provisioning methods.

To rebase an Fedora CoreOS machine to the latest uCore (stable):

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

ucore stable stream

sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/ucore:stable

ucore-hci stable stream

sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/ucore-hci:stable

ucore testing stream

sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/ucore:testing

ucore-hci testing stream

sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/ucore-hci:testing

Install with Auto-Rebase

Your path to a running uCore can be shortend by using examples/ucore-autorebase.butane as the starting point for your CoreOS ignition file.

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. Your ignition file should work for any platform, auto-rebasing to the ucore:stable, rebooting and leaving your install ready to use.

Verification

These images are signed with sigstore's cosign. You can verify the signature by downloading the cosign.pub key from this repo and running the following command:

cosign verify --key cosign.pub ghcr.io/ublue-os/ucore