gnome

name	gnome
description	Manage GNOME extensions, gsettings, and desktop customizations on Bluefin — including which settings Bluefin owns vs. which are safe to change.
domain	sysadmin

When to Use

• Managing GNOME extensions without breaking Bluefin customizations
• Reading and writing gsettings or dconf overrides
• Understanding which settings Bluefin owns vs. which are safe to change
• Customizing keyboard shortcuts, appearance, or desktop behavior

When NOT to Use

• Installing GUI applications — use Flatpak instead
• Changing system settings that require root (use ujust recipes instead)

Bluefin GNOME Overview

Bluefin ships a fully customized GNOME desktop. Customizations live in:

• projectbluefin/common — canonical source of truth at system_files/bluefin/
• System-wide dconf overrides in /etc/dconf/db/ — Bluefin-managed, user cannot easily override
• Pre-installed GNOME extensions bundled with the image

Key principle: Bluefin distinguishes between:

1. Bluefin-managed settings — in /etc/dconf/db/, set at system level, survive user resets
2. User settings — in ~/.config/dconf/, changeable freely, may be reset by image updates

GNOME Extensions

Checking what's installed:

gnome-extensions list
gnome-extensions list --enabled

GNOME Extensions app (recommended GUI):

flatpak install flathub org.gnome.Extensions

Enabling/disabling extensions:

gnome-extensions enable <extension-uuid>
gnome-extensions disable <extension-uuid>

Installing new extensions: Via GNOME Extensions app (Flatpak) → browse → install. Or via browser at https://extensions.gnome.org (requires browser integration).

Extensions bundled by Bluefin — do not disable without understanding the impact:

• Check projectbluefin/common for the authoritative list (it changes with image updates)
• Common Bluefin extensions: Dash-to-Dock, AppIndicator, Blur my Shell, etc.

Safe to customize: Non-Bluefin extensions you install yourself.

Caution: Disabling a Bluefin-bundled extension may break expected UX — it may be re-enabled on image update.

gsettings — Reading and Writing Settings

gsettings is the high-level interface for GNOME configuration.

# List all schemas
gsettings list-schemas

# List keys in a schema
gsettings list-keys org.gnome.desktop.interface

# Read a setting
gsettings get org.gnome.desktop.interface color-scheme
gsettings get org.gnome.desktop.interface gtk-theme

# Write a setting
gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'
gsettings set org.gnome.desktop.interface text-scaling-factor 1.25

# Reset to default
gsettings reset org.gnome.desktop.interface color-scheme

# Monitor changes in real time
gsettings monitor org.gnome.desktop.interface

Common schemas on Bluefin:

Schema	Purpose
org.gnome.desktop.interface	Theme, fonts, color scheme
org.gnome.desktop.background	Wallpaper
org.gnome.desktop.wm.keybindings	Window manager shortcuts
org.gnome.settings-daemon.plugins.media-keys	App shortcuts
org.gnome.shell	Shell settings, enabled extensions

dconf — Low-Level Configuration

dconf is the underlying database. Use gsettings when possible; dconf for advanced use.

# Read a key
dconf read /org/gnome/desktop/interface/color-scheme

# Write a key
dconf write /org/gnome/desktop/interface/color-scheme "'prefer-dark'"

# Dump all user settings
dconf dump /

# Dump a subtree
dconf dump /org/gnome/desktop/

# Watch for changes
dconf watch /

# Reset a key to system default (removes user override)
dconf reset /org/gnome/desktop/interface/color-scheme

# Reset an entire subtree
dconf reset -f /org/gnome/desktop/

Bluefin-managed dconf keys — in /etc/dconf/db/ (system-level locks):

# See what Bluefin locks/sets at system level
ls /etc/dconf/db/
ls /etc/dconf/db/distro.d/   # or similar
cat /etc/dconf/db/distro.d/01-bluefin  # Bluefin overrides (if present)

These take precedence over user settings and survive dconf reset.

Keyboard Shortcuts

# List current custom shortcuts
gsettings get org.gnome.settings-daemon.plugins.media-keys custom-keybindings

# Add a custom shortcut (replace [0] with next available index)
gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings \
  "['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/']"

gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  name 'Terminal'

gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  command 'ptyxis'

gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  binding '<Super>Return'

Tip: Use the Settings app → Keyboard → View and Customize Shortcuts for a GUI.

Appearance

Color scheme (dark mode):

gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'
# Options: 'default' (light), 'prefer-dark', 'prefer-light'

Wallpaper:

gsettings set org.gnome.desktop.background picture-uri "file:///path/to/image.jpg"
gsettings set org.gnome.desktop.background picture-uri-dark "file:///path/to/image.jpg"

Fonts (safe to change):

gsettings set org.gnome.desktop.interface font-name 'Inter 11'
gsettings set org.gnome.desktop.interface monospace-font-name 'Noto Sans Mono 12'

Icon themes and GTK themes: Bluefin ships default themes. Changing them is possible but may be reset on image update if Bluefin manages the setting.

Troubleshooting

Extension broken after GNOME update:

gnome-extensions disable <uuid>   # disable the broken extension
# Check extension is updated: GNOME Extensions app → check for updates
# Or reinstall: gnome-extensions install /path/to/extension.zip

Settings not sticking (reset on reboot or login):

The setting may be managed by Bluefin via /etc/dconf/db/. System settings override user settings.

# Check if the key is locked
dconf read /path/to/key   # read system-level value
# If it's Bluefin-managed, you can't override it with gsettings/dconf at user level

GNOME Shell crash after extension change:

# Disable all user extensions and restart shell (Wayland: log out and back in)
gsettings set org.gnome.shell disable-user-extensions true
# Then log out and back in

Reset all user dconf settings:

dconf reset -f /    # removes ALL user overrides — Bluefin defaults take over