{"id":20063457,"url":"https://github.com/vanilla-os/albius","last_synced_at":"2025-05-05T17:32:54.348Z","repository":{"id":66922178,"uuid":"603585703","full_name":"Vanilla-OS/Albius","owner":"Vanilla-OS","description":"A Linux installer backend with support for SquashFS and OCI installations","archived":false,"fork":false,"pushed_at":"2025-03-05T11:59:16.000Z","size":19100,"stargazers_count":21,"open_issues_count":17,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-09T02:11:15.379Z","etag":null,"topics":["installer","linux","oci","squashfs"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vanilla-OS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"COPYING.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"vanilla-os","liberapay":"fabricators"}},"created_at":"2023-02-19T00:30:25.000Z","updated_at":"2025-04-04T03:42:44.000Z","dependencies_parsed_at":"2023-11-20T13:45:54.017Z","dependency_job_id":"62420ef0-8492-4fab-9302-04b2fadd6db0","html_url":"https://github.com/Vanilla-OS/Albius","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FAlbius","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FAlbius/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FAlbius/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vanilla-OS%2FAlbius/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vanilla-OS","download_url":"https://codeload.github.com/Vanilla-OS/Albius/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252542421,"owners_count":21764967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["installer","linux","oci","squashfs"],"created_at":"2024-11-13T13:42:19.930Z","updated_at":"2025-05-05T17:32:53.849Z","avatar_url":"https://github.com/Vanilla-OS.png","language":"Go","funding_links":["https://github.com/sponsors/vanilla-os","https://liberapay.com/fabricators"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"assets/albius.png?raw=true#gh-dark-mode-only\" height=\"40\"\u003e\n\u003cimg src=\"assets/albius-mono.png?raw=true#gh-light-mode-only\" height=\"40\"\u003e\n\n---\nAlbius is a Linux installer backend originally designed for\n[Vanilla OS](https://vanillaos.org/), but capable of handling any Linux\ndistribution that uses either Squashfs or OCI images for distributing the base\nsystem. Albius is written entirely in Go and uses a recipe system (see \"recipes\"\nsubsection) for describing operations, mountpoints and options.\n\u003c/div\u003e\n\n## Motivation\n\nGiven the unorthodox filesystem structure present in Vanilla OS, most installers\nare unable to handle the distribution's installation without also requiring\nseveral patches. Furthermore, as we aim to provide a cohesive user experience\nstarting with the installation process, Vanilla OS uses a\n[custom frontend](https://github.com/Vanilla-OS/vanilla-installer) written in\nPython, further complicating the integration with other backends.\n\nAs Albius is written from the ground up to work with recipes, it can be used by\nany installation frontend or no frontend at all. The goal is to provide a\nsimple CLI tool that reads a configuration file generated by another application\nor by hand and automates all the installation steps.\n\n## Recipes\n\nRecipes are the primary way of configuring Albius and are simply a JSON file\ncontaining **setup** steps, **mountpoints** for the target system,\n**installation** options, and **post-installation** steps. A sample recipe can\nbe found in `recipe_template.json`\n\nThe full list of operations supported by the recipe system can be found in\n[RECIPE.md](https://github.com/Vanilla-OS/Albius/blob/main/RECIPE.md).\n\n### Setup\n\nThe setup section is a list of actions to take before starting the installation\nprocess itself, such as formatting the disk or creating partitions. Each step\ncontains a target disk, an operation name, and a list of parameters, like in\nthe example below:\n\n```json\n\"setup\": [\n    {\n        \"disk\": \"/dev/sda\",\n        \"operation\": \"mkpart\",\n        \"params\": [\n            \"mypart\",\n            \"btrfs\",\n            1,\n            -1\n        ]\n    }\n]\n```\nCreates a BTRFS partition in `/dev/sda` called \"mypart\" using the entire disk.\n\n### Mountpoints\n\nThis section of the recipe describes where each partition will be mounted to on\nthe installed system. Just like in the previous section, mountpoints expects a\nlist containing a partition path (`/dev/sdx1`, for example) and its corresponding\nmountpoint.\n\n```json\n\"mountpoints\": [\n    {\n        \"partition\": \"/dev/sda1\",\n        \"target\": \"/\"\n    },\n    {\n        \"partition\": \"/dev/sda2\",\n        \"target\": \"/home\"\n    }\n]\n```\nSets `/dev/sda1` as the root partition and `/dev/sda2` as the home partition.\n\n### Installation\n\nThe installation section holds options specific to the installation process,\nsuch as the installation method and filesystem source. This section contains two\ninstallation-related options: \"method\", which can be either \"unsquashfs\"\nor \"oci\", and \"source\", which describes a path for the Squashfs filesystem or\nOCI image repository, depending on the selected method.\nThe other two parameters are related to the initramfs generation, which happens\nat the end of the installation process. The user can specify optional commands\nto execute before and after this step, such as unlocking certain binaries or\npreparing the file scructure.\n\n```json\n\"installation\": {\n    \"method\": \"unsquashfs\",\n    \"source\": \"/cdrom/casper/filesystem.squashfs\"\n    \"initramfsPre\": [\"my_pre_hook\"],\n    \"initramfsPost\": [\"my_post_hook\"]\n}\n```\n\n### Post-installation\n\nSimilar to \"setup\", but this time describing steps for post-installation actions\nsuch as user creation, timezone or locale configuration, or distro-specific\nshell commands. This section expects a list of steps, each containing the\nfollowing options: whether the operation should run on the installed system\n(chroot) or on the host, the operation name, and a list of parameters.\n\n```json\n\"postInstallation\": [\n    {\n        \"chroot\": true,\n        \"operation\": \"adduser\",\n        \"params\": [\n            \"albius\",\n            \"Albius\",\n            [\n                \"sudo\",\n                \"lpadmin\"\n            ],\n            \"ASuperStrongPassword\"\n        ]\n    }\n]\n```\nCreates the user \"albius\" with the display name \"Albius\" that belongs to the\n\"sudo\" and \"lpadmin\" groups and authenticates with \"ASuperStrongPassword\".\n\n## Building\n\nSome system dependencies are required for building Albius:\n- `libbtrfs-dev`\n- `libdevmapper-dev`\n- `libgpgme-dev`\n- `lvm2`\n- A C compiler supported by CGo (`gcc`, for example)\n\nAfter the packages listed above have been installed, all that's left to do is\nrun:\n\n```sh\n$ go build\n```\n\n## Testing\n\nWriting unit tests for new functionality is encouraged to make sure everything\nstill works. All tests are executed in a loop device created before the\ntests are started. To execute the test suite, simply run:\n\n```sh\n$ sudo go test ./... -v\n```\n\nSudo is necessary in order to mount the loop device, as well as run some of the\noperations. If you're in an immutable base distribution like Vanilla OS and wish\nto run the tests in an isolated environment, keep in mind that **the tests need\nto be executed in a rootful container**. You can find a script in `utils/create_test_env.sh`\nthat automatically sets up a container for running Albius by using Distrobox.\n\n## Running\n\nAlbius accepts only one positional argument, which is the path for the recipe\nit should use to install the system. Remember to always run the binary with\nelevated privileges like in the example below:\n\n```sh\n$ sudo albius \u003cpath_for_recipe.json\u003e\n```\n\n## FAQ\n\n### Can I use this installer with an A/B root-switching structure?\n\nYes. In fact, Albius was originally tested with Vanilla OS 22.10, which used a\nSquashfs installation method with two root partitions. All you have to do is\nspecify two partitions with `\"target\": \"/\"` inside `\"mountpoints\"`.\n\n### How can I integrate Albius with my own installer?\n\nThe best way to integrate Albius with a custom installer is by saving all the\nuser options in a dictionary or hash map with the same structure described in\nthe sections above, save it to a temporary location (e.g. in `/tmp`), and then\ncall Albius by spawning a privileged shell passing the file as a parameter.\n\n### Who was Albius?\n\nAccording to [Wikipedia](https://en.wikipedia.org/wiki/Edmond_Albius), Edmond\nAlbius was a horticulturalist credited with inventing a technique for pollinating\nvanilla orchids that is both quick and efficient, which is still used to this\nday. Born into slavery in Réunion, Albius discovered the technique at the age\nof 12, which led the French colony to become the world's largest supplier of\nvanilla for some time. Although he never received the recognition he deserves\nand died in poverty at the age of 51, we hope to make more widely known the name\nof the person responsible for some of our favorite deserts. Furthermore, if an\ninstaller can be thought of as the means of reproduction for Linux distributions,\nthen Albius is responsible for spreading Vanilla OS to the world.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanilla-os%2Falbius","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanilla-os%2Falbius","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanilla-os%2Falbius/lists"}