Skip to main content

Building Aurora locally without GitHub

Most of this advice is not Aurora-specific in any way, the principles apply to every (bootable) container image.

We expect from you that you are somewhat comfortable with the usage of the commandline tools here, like git, podman, a text editor...

We will not explain everything here this is just a general outline of how things work. You should be able to look on your own to find further information about the mentioned tools here to deploy our images (man, --help, any form of documentation really)

Although don't be afraid to reach out to us if you have any questions!

Understanding Aurora's Architecture​

Aurora images are built from multiple repositories working together:

Preparations​

Build Dependencies​

Clone the main Aurora repository​

git clone https://github.com/ublue-os/aurora

Building Images​

The Justfile at the root of the repo is used to build the images, here are some examples:

CommandDescription
just buildDefaults to latest main
just build --image aurora-dxBuilds Aurora DX
just build --image aurora-dx --tag testing --flavor nvidia-openBuilds testing nvidia-open version of Aurora DX
just build --tag stable --flavor nvidia-openBuilds nvidia-open version of the Aurora stable branch
  • Images: aurora,aurora-dx
  • Tags: stable,latest,testing
  • Flavors: main,nvidia-open

We recommend you to prefix sudo with these build commands.

We use just because our image builds are rather complex because we add many build-args and labels. This just recipe basically generates one big buildah build command and verifies the authenticity of our build containers with cosign.

Testing Local Changes to Common Layers​

If you want to modify and test Aurora-specific configurations (ujust recipes, artwork, etc.) locally, follow this workflow:

Clone and Modify the Common Repository​

git clone https://github.com/get-aurora-dev/common
cd common

Make your desired changes to the common repository files.

Build the Common Container Locally​

(sudo) just build

This will create a local image tagged as localhost/aurora-common:latest.

Modify Aurora's Containerfile​

In your local ublue-os/aurora repository, you need to modify the Containerfile.in to reference your local common build instead of the remote one.

In the Containerfile.in in the root of the repository, find the FROM ${COMMON} AS common line and change it to point to your local build:

-FROM ${COMMON} AS common
+FROM localhost/aurora-common AS common

Build Aurora with Your Local Common Changes​

Now go to ublue-os/aurora and build the Aurora image:

just build

This will build Aurora using your locally modified common layer.

Building a derived image​

Of course you can also build a derived image using the classical container workflow instead of building Aurora "from scratch".

FROM ghcr.io/ublue-os/aurora:stable

RUN ...

We recommend the image-template

Test Your Changes​

This heavily depends on the changes you make but the safest option is to create a VM with the disk-image recipe and boot it with qemu. This is the closest to installing Aurora from the Installation ISO.

Iterate​

If you need to make more changes:

  1. Modify files in the common repository
  2. Rebuild the common container
  3. Rebuild the Aurora image
  4. Rebase to the new local image

Contributing Your Changes​

Once you've tested your changes locally:

  • For Aurora-specific features (configurations, artwork, Aurora ujust recipes), submit a pull request to get-aurora-dev/common
  • For shared features that affect both Aurora and Bluefin (base ujust recipes, MOTD, CLI config), contribute to ublue-os/aurorafin-shared
  • For Homebrew-related changes, contribute to ublue-os/brew
  • For changes to the Aurora image itself (installed packages, build scripts), contribute to ublue-os/aurora

Make sure to only commit the actual changes to the repo with things like git add -p.

Rebasing to a Locally Built Image​

For bootc to be able to rebase/switch to the new image it has to be moved from the users container storage to the container storage of the root user.

podman image scp localhost/aurora:latest root@localhost

You can also add sudo before the just build commands, then you don't need to do the podman image scp part.

sudo bootc switch --transport containers-storage localhost/aurora:latest

and lastly reboot into the new image

systemctl reboot

Testing Without Building an Image​

Makes /usr writable for the duration of this boot, this is usually sufficient to test very simple things.

overlayfs over /usr​

sudo bootc usr-overlay

Use dnf or make whatever modification to /usr as you wish.

sudo dnf install/swap/remove/downgrade ...

Reboot to undo any changes you made after the overlayfs on /usr is mounted.

Another way to do this without rebooting the system:

sudo rm /run/ostree/deployment-state/*.0/unlocked-development
sudo umount -l /usr

Remember that /etc and /var are not reverted after a reboot so you can still very much screw yourself over and have leftover files there!

You can also create a more persistent overlay:

Could be useful for firmware downgrades or triaging bugs that only happen on shutdown etc.

sudo ostree admin unlock --hotfix
rpm-ostree status
● ostree-image-signed:docker://ghcr.io/ublue-os/aurora-dx:stable
                   Digest: sha256:4d08e32db51d634eb6fa1cf27e8472de074db783aee5c89849899e00c36c4b59
                  Version: 42.20250630 (2025-06-30T04:54:48Z)
                 Unlocked: hotfix
sudo dnf -y downgrade atheros-firmware-20250311-1$(rpm -E %{dist})

To get rid of this writable deployment you can either just (wait for an) update and it will get cleaned up eventually or you boot into the previous deployment from Grub and run:

rpm-ostree cleanup --pending