Lib.rs

Normal people don't reinstall their OS from scratch very often. When they do, the moment they reach that pristine desktop or terminal after a clean installation, all hell breaks loose. Settings get changed, applications are installed, bloatware is removed, files get downloaded here and there. The system is generally altered from its original state into a new "customized" state by a manual flurry of mouse clicks and key presses.

If you think about your system like a server, this approach is called mutable infrastructure, meaning you mutate the state of your system repeatedly until it eventually suits your needs. And when something goes awry, you have to make the necessary changes to get it back in line.

For normal people, mutable infrastructure works out fine until something major breaks or they have to migrate to a new computer altogether. In these cases, they probably end up starting over from scratch and have to reapply their changes again (and probably differently this time).

Slightly less normal people might have scripts or even use a configuration management tool like Ansible or Puppet to automate all of those customizations. This is great, but you can't start at a boot prompt and immediately run an Ansible playbook. Something (or someone) has to install the OS before the automation can be "kicked off". Also, configuration management tools have limited scope.

Truly sophisticated computer elites practice immutable infrastructure. Meaning that, every time they boot their system, its state begins identically to the time before. Any changes that are made during the course of runtime vanish on reboot. This approach has some real benefits, but requires quite a bit of effort from the user.

If you're looking to achieve something close to immutable infrastructure without creating a lot of extra work for yourself, you've come to the right place.

In the goldboot approach, you choose a starting template containing an absolutely minimal install of your favorite OS. Then you create provisioners which are the scripts that add all of your customizations on top of the template. From these pieces, goldboot builds a machine image ready to be deployed to real hardware.

Warning: this tool is totally unfinshed and should be used for testing only! Proceed at your own risk!

If computer programs could reproduce sexually, goldboot is what you would get if docker and packer were mixed together.

More practically, goldboot is a command-line tool that builds machine images for real hardware instead of containers or virtual machines.

These machine images (also known as golden images) contain your operating system(s), applications, software patches, and configuration all rolled into one easily deployable package.

Like Docker images, your goldboot images can be stored in a registry and pulled onto real hardware.

Examples

The goldboot-examples repo contains example configurations of all supported OS types and system architectures. They are built on a weekly schedule against the latest version of goldboot.

Linux	Windows	macos

Installation

alias goldboot="docker run --rm -v .:/root fossable/goldboot"

cargo install goldboot

  cd /tmp
  curl https://aur.archlinux.org/cgit/aur.git/snapshot/goldboot.tar.gz | tar xf -
  makepkg -si

steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Build goldboot image
    uses: fossable/goldboot-action@main
    with:
      config-path: goldboot.json
      output-path: image.gb

  - name: Save image artifact
    uses: actions/upload-artifact@v3
    with:
      name: my_image.gb
      path: image.gb

Your first golden image

Let's build a basic image to prove we're real Linux users.

First, create a directory to hold our configuration (which can later be tracked in version control):

mkdir Test && cd Test

Initialize the directory and choose ArchLinux to start with:

goldboot init \
  --name Test \
  --mold ArchLinux \
  --size 10G \
  --format json

This will create goldboot.json which contains configuration options that can be tweaked to suit your needs. For example:

{
  "alloy": [
    {
      "mold": {
        "ArchLinux": {
          "hostname": "YeahIUseArch",
          "root_password": {
            "plaintext": "123456"
          }
        }
      },
      "source": {
        "Iso": {
          "url": "https://mirrors.edge.kernel.org/archlinux/iso/2024.01.01/archlinux-2024.01.01-x86_64.iso",
          "checksum": "sha256:12addd7d4154df1caf5f258b80ad72e7a724d33e75e6c2e6adc1475298d47155"
        }
      }
    }
  ],
  "arch": "Amd64",
  "name": "Test",
  "size": "10G"
}

There are many ways to customize the image, but for now just build it:

goldboot build .

Once the build succeeds, the image will be saved to the system's library directory. To deploy it to a physical disk, you can use a bootable USB drive:

# THIS WILL OVERWRITE /dev/sdX!
goldboot make_usb --output /dev/sdX --include Test

Once the USB is created, you can use it to boot into the goldboot live environment and select an image to write:

Once the image has been applied, remove the bootable USB drive and reboot the machine.