Shared OCI layer containing common configuration files used across all Bluefin variants (bluefin, bluefin-dx, bluefin-lts).
This repository organizes configuration files into two main directories, these are important:
Files specific to Bluefin
- GNOME desktop settings and theming
- Bluefin wallpapers and branding
- Desktop-specific environment variables
- GNOME Initial Setup configuration
Files that are shared with Aurora are in aurorafin-shared, other images can use this as a git submodule or copying or as part of a container build, see below.
This includes:
Justrecipes for system management- Brewfiles for application bundles
- Setup hooks (privileged, system, user)
- Container policies and security settings
- MOTD templates and CLI bling
- Common shell configurations
Reference this layer as a build stage and copy the directories you need:
FROM ghcr.io/projectbluefin/common:latest AS bluefin-common
# Copy all system files
COPY --from=bluefin-common /system_files /FROM ghcr.io/projectbluefin/common:latest AS bluefin-common
# Copy only /etc configuration
COPY --from=bluefin-common /system_files/etc /etcFROM ghcr.io/projectbluefin/common:latest AS bluefin-common
# Copy only /usr/share configuration
COPY --from=bluefin-common /system_files/usr /usrBluefin-common provides a comprehensive flatpak customization system with multiple layers:
Default flatpaks are now managed via Homebrew Brewfiles, allowing for declarative system-wide installation:
system-flatpaks.Brewfile- Core flatpaks installed on all Bluefin variants (37 applications including Firefox, Thunderbird, GNOME Circle apps, and utilities)system-dx-flatpaks.Brewfile- Additional development-focused flatpaks for DX mode (6 applications including Podman Desktop, Builder, and DevToolbox)
These can be installed using:
ujust install-system-flatpaksTwo types of flatpak overrides are provided to grant additional permissions to specific applications:
System-level overrides (/usr/share/ublue-os/flatpak-overrides/):
io.github.kolunmi.Bazaar- Grants access tohost-etcfor system configuration
User-level overrides (/etc/skel/.local/share/flatpak/overrides/):
com.visualstudio.code- Enables Wayland support and Podman socket accesscom.google.Chrome- Grants access to local applications and icons directories
These overrides are automatically applied to new user accounts through the /etc/skel template.
The /usr/share/ublue-os/homebrew/ directory contains curated application bundles installable via bbrew:
system-flatpaks.Brewfile- Default system-wide flatpaks for all Bluefin variantssystem-dx-flatpaks.Brewfile- Additional flatpaks for DX (Developer Experience) modefull-desktop.Brewfile- Comprehensive collection of GNOME Circle and community flatpak applications for a full desktop experiencefonts.Brewfile- Additional monospace fonts for developmentcli.Brewfile- CLI tools and utilitiesai-tools.Brewfile- AI and machine learning toolscncf.Brewfile- Cloud Native Computing Foundation toolsk8s-tools.Brewfile- Kubernetes toolside.Brewfile- Integrated development environmentsartwork.Brewfile- Design and artwork applications
Users can install these bundles using the ujust bbrew command, which will prompt them to select a Brewfile.
Changes are validated in two stages:
On every PR — lightweight checks only (no VM boot):
validate-just— lints the Justfile and all.justrecipesbuild— builds the OCI image withbuildah
On merge to main — full layer validation via projectbluefin/testsuite:
- Runs the
commonbehave suite against Bluefin LTS, Bluefin Stable, and Dakota - SSH-mode: behave runs from the GHA runner over SSH into a QEMU VM — no full GNOME session needed, completes in ~15 min
- Validates dconf defaults, locked keys,
ujust, setup scripts, desktop entries, and shell configuration as they land in the composed images
just build