Mastodon Skip to content
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.


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.


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.
    • New curious tinkerers won’t be robbed of the experience of learning a new generalizeable skill, as we also (plan to) provide documentation for setting up the pipelines and building container images from scratch.
  • It allows us to make harder things simpler.
    • For just installing packages the system might be less useful, but for more complex build-time customizations it becomes way simpler to use a commonly maintained module instead.
  • It allows for parts of the build system be shared.
  • 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 updateable 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 need some help setting up the GitHub Actions for that, check out our guide for building a build system from scratch.

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.