Building your own image¶

CasadoraOS is designed to be forked. The Containerfiles are short on purpose so your customizations stay maintainable alongside upstream changes.

Fork the repo¶

git clone https://github.com/YOUR-USER/casadora-os.git
cd casadora-os

Understand the structure¶

containers/
  orion/
    Containerfile
  proxima/
    Containerfile

Each image is a single Containerfile. Read one from top to bottom — you'll find the base image, package installs, user creation, systemd services, and quadlet definitions all in one place.

Create a new target¶

1. Copy an existing Containerfile as a starting point:

mkdir containers/my-target
cp containers/orion/Containerfile containers/my-target/Containerfile

1. Edit the Containerfile to match your hardware and role.

2. Build the image:

podman build -t my-target containers/my-target/

1. Build a disk image with bootc-image-builder:

bootc-image-builder --type qcow2 localhost/my-target:latest

Keep in sync with upstream¶

Add the original repo as a remote and rebase your changes:

git remote add upstream https://github.com/CasadoraTech/casadora-os.git
git fetch upstream
git rebase upstream/main

Since each target is its own Containerfile, merge conflicts are rare — your customizations live in separate files from upstream targets.

CI integration¶

The repo's GitHub Actions workflow can build and publish custom images. Add your target to the build matrix in .github/workflows/ and push — CI handles the rest.

Tips¶

• Start small. Copy the simplest existing Containerfile and add packages one at a time.
• Test locally. podman build catches most issues before you flash hardware.
• Use quadlets. If you're adding a service, ship it as a Podman quadlet rather than a systemd unit — it's the pattern all CasadoraOS images follow.
• Pin your base. Set a specific tag in your FROM line so builds are reproducible.