Mastodon Skip to content
Docs
Hey! We're still a pretty new project and are moving fast, but trying to keep a degree of backwards compatibality when changes are made. Contributions are very welcome!
A minimal logo with a blue-billed duck holding a golden wrench in its beak.

The easiest way to build your own desktop Linux images.

The BlueBuild project creates accessible tools for you to create, configure & build custom images of atomic Fedora distributions.

Features


Easy configuration

The build process can be configured entirely in a straightforward YAML format called a recipe. When building, the recipe is transformed into a Containerfile by the BlueBuild cli tool.

Totally extensible

The modular build system can easily be extended by just writing a shell script. Modules you create can be added into the official BlueBuild repository, or your own, for the community to take advantage of.

Based on well-known standards

The format of your OS images is the familiar OCI image format, famously used by Docker & Podman. With Fedora’s Native Container support, it becomes possible to boot natively into a OCI compatible image.

Free & open-source

BlueBuild is an open-source project built by the community for the community. Feel free to peek at & tinker with the source code! GitHub also provides CI/CD & a container registry for free, though other providers are supported as well.

Effortless reliability

With your custom images being based on reliable atomic distributions, your setup will be rock solid. As all errors related to customizing your environment happen during the build process in the cloud, it’s way harder to end up with a bricked system.

FAQ

What’s a custom image? Can I use this to make my own distro?

A custom image in this context is a customized version of an image-based Linux distribution that can be switched to by the user of such a distribution without reinstalling. So about making your own distro, maybe, but not really. When making custom images, you’re building on top of an existing distribution. You’re most likely using its package manager and repositories and just adding your own flair with package set changes and configuration files. It’s more like a more reliable version of maintaining/sharing your dotfiles, but from the perspective of the operating system.

So is this the type of workaround necessary to make ‘immutable’ distributions customizable?

Someone might get turned off from so-called ‘immutable’ Linux distributions due to fears of the taking away them ability to tinker and change the system as you please. The term comes from the usage of immutable root filesystems in these distributions, but in reality most ‘immutable’ Linux distributions are still pretty change-able. So while BlueBuild is a tool that helps you tinker with these sorts of distributions, it’s not giving you back some freedom that was taken away.

Here’s some terms that can be used to better describe these sorts of distributions:

Atomic: instead of new and updated packages being swapped on the running system live, they’re queued up to be used after the next boot.
Image-based: instead of each computer updating each of its system packages individually, the system updates are bundled (usually daily) as images that are pulled onto the user computers and queued up to be used after the next boot.

Read more here.

What’s the difference between BlueBuild and VanillaOS’ Vib?

BlueBuild and Vib seem very similar and both use similar concepts: recipes and modules. While Vib technically does the same thing as BlueBuild, it is positioned more as a generalized tool to build any OCI container image that just happens to be what is used by Vanilla to build their desktop. BlueBuild focuses on image-based desktop Linux more than containers, using container images as just a distribution mechanism. As such, BlueBuild supports more features specifically useful on desktop by default, such as the fonts module to fetch a selection of fonts.

BlueBuild also aims to support building custom images of VanillaOS in the near future.

And in the FAQ writer’s opinion, BlueBuild’s documentation is better and the recipe format is slightly cleaner.

What’s the difference between BlueBuild and Universal Blue?

Universal Blue is an open source project started by cloud developers that builds amazing custom images based on atomic Fedora along with related experiments, while BlueBuild only builds tools for custom image creation. The project now known as BlueBuild started out as just a part of Universal Blue, but was eventually split from it due to diverging from the scope and being mostly unrelated to the project’s main maintainers.

Why build an abstraction on top of Containerfiles? (recipe.yml)

  • It is more accessible and helps onboard new users.
    • Editing a configuration file is something most people are likely familiar with, but editing a Containerfile, bespoke build scripts, and a GitHub Action file is something most probably have no prior experience with.
  • It allows us to make harder things easier.
    • For just installing packages the system might be less useful, but for more complex customizations it becomes way easier to use a commonly maintained module instead.
  • It allows for parts of the build system be shared.
    • Less moving parts for everyone to maintain on their own.
    • Discuss and keep useful patterns up-to-date as community.
  • It allows for tooling to be created that programmatically configures custom images for users.

Is this project for me?

If you want an easy way to package your customization for use on multiple computers, or maybe even have a lab of full-fledged Linux computers that you want on the same centrally updatable base, BlueBuild might just be what you’re looking for! Or maybe you’re a tinkerer looking for a new and exciting space in Linux to dabble with, then this and related projects are definitely something to put on your radar.

But if you’re a total Linux and cloud nerd, you know Containerfiles by heart and are comfortable building CI/CD, our abstractions might feel limiting to you. You should still come hang around if you’re interested in building custom images!

If you’re just looking to build a simple container image to run on the cloud or locally, a Containerfile might still be the easiest way to get the result you want. If you want to learn how to build OCI container images with Containerfiles by making a custom image of atomic Fedora, the ublue-os/image-template is a good minimal place to start.

If you want to leverage BlueBuild’s modules for making more complex customizations to your image, while using a Containerfile directly, check out our guide for a minimal BlueBuild module setup in a Containerfile. Keep in mind that this approach is not guaranteed to be as seamless as using a recipe and to not have breaking changes. When not using a recipe, you’re also losing out on a lot of the magic of the BlueBuild CLI, such as being able to switch to the image built from a recipe locally with just one command.

Are you stable?

Yes and no. We may make breaking changes and refactorings, but current existing configurations will be supported to the best of our abilities. Besides, changes in the tooling should not affect the stability of your actual operating system.

It’s our mascot, a blue-billed duck with a wrench! A good pun, and cute too! The writer of this FAQ is definitely not at all biased!

The logo (along with all the other BlueBuild branding) was designed by @xynydev and is licensed under CC BY-NC-SA 4.0.