Lisa Blog

Lisa Server: its own image, from the same release

· The Lisa team
serverimagerelease

Lisa comes in flavours of one platform: the same frameworks, the same contracts, the same release. Lisa Server is the one for machines that nobody sits in front of: a rented box at a provider, a VPS, a machine in a cupboard at home. It has no display and nothing graphical in it. You steer it from a browser, through Bridge, or from a desktop with the lisa server commands.

This post is about the server itself: what it is, how it gets onto a machine, and the decision we reversed on the way.

A decision we reversed

On 4 September we ruled that Lisa would be one image, with “server” a role you turn on. That is how the reference platform ships its server: as an application on the same operating system.

A day later we reversed it. Lisa Server is now its own image, lisaos-server, beside lisaos-desktop. Both are built from the same reviewed lock at the same pins, signed by the same root, and published together as one release.

The cost of the split is real, and we accepted it: two recipes, and two sets of update tests per architecture. What it buys is worth more. A server carries no compositor, no Flutter engine, no Shell and no applications at all, so nothing on it can fail for want of a display. Nothing graphical has to be switched off, because nothing graphical was ever put in.

Where the two images split

Both images start from the same core image, built once per architecture: the base and its kernel and drivers; the Fedora substrate (systemd, the bus, NetworkManager, sshd, Podman, polkit, chrony, firewalld); Lisa’s core daemons and the lisa command at one commit; the updater; and the signing and the channel. A difference between the two images that the release lock does not name is a defect.

The split happens at build time. The desktop image adds the compositor, the Embedder, the Shell, the login, the applications and the fonts. The server image adds Bridge, its firewall configuration and the server half of lisa setup. Nothing is removed at setup, because there is nothing extra to remove.

A machine is a desktop or a server because of the image it boots, decided when the release was built. To change flavour you install the other image; there is no toggle afterwards.

One command, over whatever Linux is already there

Rented boxes come with whatever Linux the provider chose. So Lisa Server installs over it, from one line run as root:

curl -fsSL https://os.lisaos.dev/install | sh

It runs on Fedora, Debian, Ubuntu, Alma, Rocky, CentOS, openSUSE, Arch and Alpine, on x86_64 and aarch64. When the box lacks something, it fetches it through that distribution’s own package manager: Podman, which carries the bootc installer, and Python, which reads the release channel.

It asks three things: the domain Bridge will answer at, the machine’s name, and a password. Then it does the rest without asking again:

  1. It reads the channel for the current server release.
  2. It fetches that image and checks its digest against the signed targets.
  3. It installs the image over the box with bootc.
  4. It takes your SSH key from root’s authorised keys.
  5. It seeds the domain, name and password for the first boot, and asks for a reboot.

On first boot, lisa setup runs by itself. It creates the machine’s lisa account with your key and password, brings Bridge up at your domain, turns the firewall on with SSH, HTTP and HTTPS allowed, and finally deletes the previous system’s files from the disk. The machine is Lisa and nothing else. That is the same shape as the one-line installer for Linux on Apple silicon.

No domain? No problem. Leave it empty and the machine gets a name of Lisa’s own, <machine>.lisaos.cloud, from Lisa’s name service.

What it trusts. The installer trusts the release origin over HTTPS, once, and carries no key of its own. After that, the machine trusts only the signed release channel, verified by the updater against the trusted root built into the image.

Updates are the image

A Lisa server never upgrades package by package. The updater checks the signed channel, stages the new image in the background, verifies it, and switches at the next start. If the new image does not come up healthy, the machine goes back to the old one. Bridge does not update itself either: it arrives inside the server image, and the image is what updates.

The machine’s own facade

On a server, one daemon is the machine’s facade: serverd. It serves the service units, the firewall, the disks, the machine’s accounts and the scheduled tasks over the bus, using systemd, firewalld and the kernel. It holds nothing of its own about any of them, except the scheduled tasks it created. Bridge’s System view calls serverd; it does not touch systemd or firewalld behind its back.

How we prove it

We prove a server the way we would use one: on a real rented box, through the real channel. In early September a Hetzner server, born as Ubuntu, was installed by the one command, took five releases through the channel, had each proved, and was deleted the same evening.

The rule is simple: a test box is installed, proven and deleted, so nothing idle is paid for. The channel keeps the releases, and the next machine installs with the same one line.

What is not done

  • No server runs Lisa today. That is the rule above, not an accident. The next one installs when there is a release worth proving.
  • The one command has only run on Hetzner boxes. Other providers and home machines are expected to work, and are not yet proven.
  • Some of Bridge’s Hosting actions still call Podman directly. Deploying, pushing and naming an app don’t yet go through the server’s own container daemon.

The install path is written down in full in Installing Lisa, and the image split in The image.

← All posts