KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

Albius

★ 30 Open GitHub ↗

A Linux installer backend with support for SquashFS and OCI installations

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

---
Albius is a Linux installer backend originally designed for
[Vanilla OS](https://vanillaos.org/), but capable of handling any Linux
distribution that uses either Squashfs or OCI images for distributing the base
system. Albius is written entirely in Go and uses a recipe system (see "recipes"
subsection) for describing operations, mountpoints and options.
</div>

## Motivation

Given the unorthodox filesystem structure present in Vanilla OS, most installers
are unable to handle the distribution's installation without also requiring
several patches. Furthermore, as we aim to provide a cohesive user experience
starting with the installation process, Vanilla OS uses a
[custom frontend](https://github.com/Vanilla-OS/vanilla-installer) written in
Python, further complicating the integration with other backends.

As Albius is written from the ground up to work with recipes, it can be used by
any installation frontend or no frontend at all. The goal is to provide a
simple CLI tool that reads a configuration file generated by another application
or by hand and automates all the installation steps.

## Recipes

Recipes are the primary way of configuring Albius and are simply a JSON file
containing **setup** steps, **mountpoints** for the target system,
**installation** options, and **post-installation** steps. A sample recipe can
be found in `recipe_template.json`

The full list of operations supported by the recipe system can be found in
[RECIPE.md](https://github.com/Vanilla-OS/Albius/blob/main/RECIPE.md).

### Setup

The setup section is a list of actions to take before starting the installation
process itself, such as formatting the disk or creating partitions. Each step
contains a target disk, an operation name, and a list of parameters, like in
the example below:

```json
"setup": [
    {
        "disk": "/dev/sda",
        "operation": "mkpart",
        "params": [
            "mypart",
            "btrfs",
            1,
            -1
        ]
    }
]
```
Creates a BTRFS partition in `/dev/sda` called "mypart" using the entire disk.

### Mountpoints

This section of the recipe describes where each partition will be mounted to on
the installed system. Just like in the previous section, mountpoints expects a
list containing a partition path (`/dev/sdx1`, for example) and its corresponding
mountpoint.

```json
"mountpoints": [
    {
        "partition": "/dev/sda1",
        "target": "/"
    },
    {
        "partition": "/dev/sda2",
        "target": "/home"
    }
]
```
Sets `/dev/sda1` as the root partition and `/dev/sda2` as the home partition.

### Installation

The installation section holds options specific to the installation process,
such as the installation method and filesystem source. This section contains two
installation-related options: "method", which can be either "unsquashfs"
or "oci", and "source", which describes a path for the Squashfs filesystem or
OCI image repository, depending on the selected method.
The other two parameters are related to the initramfs generation, which happens
at the end of the installation process. The user can specify optional commands
to execute before and after this step, such as unlocking certain binaries or
preparing the file scructure.

```json
"installation": {
    "method": "unsquashfs",
    "source": "/cdrom/casper/filesystem.squashfs"
    "initramfsPre": ["my_pre_hook"],
    "initramfsPost": ["my_post_hook"]
}
```

### Post-installation

Similar to "setup", but this time describing steps for post-installation actions
such as user creation, timezone or locale configuration, or distro-specific
shell commands. This section expects a list of steps, each containing the
following options: whether the operation should run on the installed system
(chroot) or on the host, the operation name, and a list of parameters.

```json
"postInstallation": [
    {
        "chroot": true,
        "operation": "adduser",
        "params": [
            "albius",
            "Albius",
            [
                "sudo",
                "lpadmin"
            ],
            "ASuperStrongPassword"
        ]
    }
]
```
Creates the user "albius" with the display name "Albius" that belongs to the
"sudo" and "lpadmin" groups and authenticates with "ASuperStrongPassword".

## Building

Some system dependencies are required for building Albius:
- `libbtrfs-dev`
- `libdevmapper-dev`
- `libgpgme-dev`
- `lvm2`
- A C compiler supported by CGo (`gcc`, for example)

After the packages listed above have been installed, all that's left to do is
run:

```sh
$ go build
```

## Testing

Writing unit tests for new functionality is encouraged to make sure everything
still works. All tests are executed in a loop device created before the
tests are started. To execute the test suite, simply run:

```sh
$ sudo go test ./... -v
```

Sudo is necessary in order to mount the loop device, as well as run some of the
operations. If you're in an immutable base distribution like Vanilla OS and wish
to run the tests in an isolated environment, keep in mind that **the tests need
to be executed in a rootful container**. You can find a script in `utils/create_test_env.sh`
that automatically sets up a container for running Albius by using Distrobox.

## Running

Albius accepts only one positional argument, which is the path for the recipe
it should use to install the system. Remember to always run the binary with
elevated privileges like in the example below:

```sh
$ sudo albius <path_for_recipe.json>
```

## FAQ

### Can I use this installer with an A/B root-switching structure?

Yes. In fact, Albius was originally tested with Vanilla OS 22.10, which used a
Squashfs installation method with two root partitions. All you have to do is
specify two partitions with `"target": "/"` inside `"mountpoints"`.

### How can I integrate Albius with my own installer?

The best way to integrate Albius with a custom installer is by saving all the
user options in a dictionary or hash map with the same structure described in
the sections above, save it to a temporary location (e.g. in `/tmp`), and then
call Albius by spawning a privileged shell passing the file as a parameter.

### Who was Albius?

According to [Wikipedia](https://en.wikipedia.org/wiki/Edmond_Albius), Edmond
Albius was a horticulturalist credited with inventing a technique for pollinating
vanilla orchids that is both quick and efficient, which is still used to this
day. Born into slavery in Réunion, Albius discovered the technique at the age
of 12, which led the French colony to become the world's largest supplier of
vanilla for some time. Although he never received the recognition he deserves
and died in poverty at the age of 51, we hope to make more widely known the name
of the person responsible for some of our favorite deserts. Furthermore, if an
installer can be thought of as the means of reproduction for Linux distributions,
then Albius is responsible for spreading Vanilla OS to the world.

Albius

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README