bluefin-common

Shared OCI layer containing common configuration files used across all Bluefin variants (bluefin, bluefin-dx, bluefin-lts).

Directory Structure

This repository organizes configuration files into two main directories, these are important:

system_files/bluefin/ - Bluefin Specific Configuration

Files specific to Bluefin

• GNOME desktop settings and theming
• Bluefin wallpapers and branding
• Desktop-specific environment variables
• GNOME Initial Setup configuration

system_files/shared/ - Shared Configuration

Files shared with Aurora — Aurora maintainers can cherry-pick commits touching this directory. Edit directly here; changes propagate to all Bluefin variants on next build.

This includes:

• Just recipes 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

Usage in Containerfile

Reference this layer as a build stage and copy the directories you need:

Copy everything:

FROM ghcr.io/projectbluefin/common:latest AS bluefin-common

# Copy all system files
COPY --from=bluefin-common /system_files /

Copy only system configuration:

FROM ghcr.io/projectbluefin/common:latest AS bluefin-common

# Copy only /etc configuration
COPY --from=bluefin-common /system_files/etc /etc

Copy only the image opinion:

FROM ghcr.io/projectbluefin/common:latest AS bluefin-common

# Copy only /usr/share configuration
COPY --from=bluefin-common /system_files/usr /usr

Flatpak Customization

Bluefin-common provides a comprehensive flatpak customization system with multiple layers:

System Flatpak Brewfiles

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-flatpaks

Flatpak Overrides

Two 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 to host-etc for system configuration

User-level overrides (/etc/skel/.local/share/flatpak/overrides/):

• com.visualstudio.code - Enables Wayland support and Podman socket access
• com.google.Chrome - Grants access to local applications and icons directories

These overrides are automatically applied to new user accounts through the /etc/skel template.

Flatpak Update Schedule

Automatic updates are handled by uupd, which updates the system image, Flatpaks, Distrobox containers, and Homebrew together. To keep image updates enabled while choosing a different Flatpak cadence, disable only uupd's Flatpak module.

/etc/uupd/config.json ships on every image — it already sets modules.distrobox.disable = true — so it always exists and must be edited with jq, never overwritten with a fresh payload. This snippet refuses to install an empty or invalid result, so a missing jq or a failed edit cannot wipe the shipped config:

command -v jq   # required; install jq first if this prints nothing
tmp="$(mktemp)"
sudo jq '.modules.flatpak.disable = true' /etc/uupd/config.json >"$tmp" \
    && jq -e . "$tmp" >/dev/null \
    && sudo install -m 0644 "$tmp" /etc/uupd/config.json
rm -f "$tmp"

The configuration is read on each uupd run, so it applies to the next scheduled update. Do not edit /usr/lib/systemd/system/uupd.timer; image updates replace files there. To change only the schedule, write a drop-in with sudo systemctl edit uupd.timer, which lives under /etc and survives image updates.

After disabling the module, create local systemd service and timer units under /etc/systemd/system (or user units under ~/.config/systemd/user) that run flatpak update --system --noninteractive and/or flatpak update --user --noninteractive at the cadence you want. For example, this system-wide timer runs Flatpak updates every 60 days:

# /etc/systemd/system/flatpak-system-update.service
[Unit]
Description=Update system Flatpaks

[Service]
Type=oneshot
ExecStart=/usr/bin/flatpak update --system --noninteractive

# /etc/systemd/system/flatpak-system-update.timer
[Timer]
OnBootSec=15min
OnUnitActiveSec=60d
Persistent=true

[Install]
WantedBy=timers.target

Enable it with sudo systemctl daemon-reload and sudo systemctl enable --now flatpak-system-update.timer. Keep custom units under /etc or ~/.config so they survive image updates. Set modules.flatpak.disable to false or remove it to return Flatpak updates to the normal uupd.timer schedule.

Brewfiles

The /usr/share/ublue-os/homebrew/ directory contains curated application bundles installable via bbrew:

• system-flatpaks.Brewfile - Default system-wide flatpaks for all Bluefin variants
• system-dx-flatpaks.Brewfile - Additional flatpaks for DX (Developer Experience) mode
• full-desktop.Brewfile - Comprehensive collection of GNOME Circle and community flatpak applications for a full desktop experience
• fonts.Brewfile - Common fonts for everyday work
• fonts-dev.Brewfile - Additional monospace fonts for development
• cli.Brewfile - CLI tools and utilities
• ai-tools.Brewfile - AI and machine learning tools
• cncf.Brewfile - Cloud Native Computing Foundation tools
• k8s-tools.Brewfile - Kubernetes tools
• ide.Brewfile - Integrated development environments
• artwork.Brewfile - Design and artwork applications

Users can install these bundles using the ujust bbrew command, which will prompt them to select a Brewfile. The local Bluespeed stack can be installed directly with ujust bluespeed.

CI / Testing

Changes are validated in three layers:

If you need the per-workflow purpose and ownership map, start with docs/skills/workflow-map.md.

On every PR:

• validate.yml — just check, shellcheck, pre-commit, submodule drift, registry/dconf guards
• build.yml — builds the OCI image with buildah
• skill-drift.yml — warns when implementation changes land without matching skill-doc updates
• pr-e2e.yml — advisory composed-image common-suite check against a downstream Bluefin base

On merge to main — full layer validation via projectbluefin/testsuite:

• Runs the common behave 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

Before downstream testing → stable promotions:

• promotion-candidate-e2e.yml runs smoke,common against ghcr.io/projectbluefin/bluefin:{testing,lts-testing} on Tuesdays, giving common a repo-local signal on the exact candidate tags that feed promotion

Building Locally

just build

Contributor Metrics