Add comprehensive Omarchy analysis document
Reference document covering the upstream Omarchy project architecture, installation process, package management, desktop stack, theming system, boot management, ISO generation, omacom-io ecosystem, and Arch-to-Debian mapping table for planning the Yino port. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
4b43829849
commit
eeee7ace7d
768
docs/Omarchy.md
Normal file
768
docs/Omarchy.md
Normal file
@ -0,0 +1,768 @@
|
||||
# Omarchy Analysis
|
||||
|
||||
A comprehensive reference document analyzing the upstream Omarchy project and its ecosystem, serving as a
|
||||
blueprint for the Yino (Debian-based) port.
|
||||
|
||||
## 1. Project Overview
|
||||
|
||||
Omarchy ("Beautiful, Modern & Opinionated Linux") is an omakase Linux distribution created by David Heinemeier
|
||||
Hansson (DHH), the creator of Ruby on Rails and co-founder of 37signals/Basecamp. The name derives from
|
||||
"omakase" -- a Japanese dining concept where a master chef prepares a curated selection rather than the diner
|
||||
choosing from a menu.
|
||||
|
||||
- **Repository:** [github.com/basecamp/omarchy](https://github.com/basecamp/omarchy)
|
||||
- **Website:** [omarchy.org](https://omarchy.org)
|
||||
- **Manual:** [learn.omacom.io](https://learn.omacom.io/2/the-omarchy-manual)
|
||||
- **License:** MIT
|
||||
- **Stars:** ~20,100 | **Forks:** ~2,000 | **Contributors:** 333
|
||||
- **Latest Release:** v3.3.3 (2026-01-08) | **Total Releases:** 48 | **Commits:** 3,214
|
||||
- **Default Branch:** `dev`
|
||||
- **Language:** Shell (91.8%), CSS (3.1%), Go Template (3.1%), Lua (1.8%)
|
||||
- **Sponsor:** Cloudflare (provides CDN for ISO and package delivery)
|
||||
|
||||
DHH first built Omakub (an Ubuntu-based configuration) when he initially switched to Linux. After running it as
|
||||
his daily driver for over a year, he evolved to a more advanced Arch-based setup and published Omarchy on June
|
||||
26, 2025 as "a love letter to Linux." 37signals subsequently announced going all-in on Omarchy, planning to
|
||||
switch everyone on their Ops and Ruby programming teams to it over three years. By October 2025, a petabyte of
|
||||
ISOs had been delivered in a single month (~150,000 installs).
|
||||
|
||||
Omarchy turns a fresh Arch Linux installation into a fully-configured, keyboard-driven desktop development system
|
||||
based on Hyprland. It ships with Neovim, Ghostty, Spotify, Chromium, Typora, LibreOffice, and more.
|
||||
|
||||
Key characteristics:
|
||||
- Mandatory full-disk LUKS encryption
|
||||
- UFW firewall enabled by default
|
||||
- Wayland-only (no X11)
|
||||
- Single-user auto-login (disk decryption authenticates the user)
|
||||
- Btrfs filesystem with Snapper snapshots
|
||||
- 14 built-in themes with atomic switching
|
||||
- Super key as the primary modifier
|
||||
|
||||
## 2. Repository Structure
|
||||
|
||||
```
|
||||
basecamp/omarchy/
|
||||
├── .github/ISSUE_TEMPLATE/
|
||||
├── applications/ # Desktop entries, icons for TUIs and web apps
|
||||
│ └── icons/
|
||||
├── bin/ # ~100+ executable scripts (omarchy-* commands)
|
||||
├── config/ # Default config files for all components
|
||||
│ ├── hypr/ # Hyprland, Hypridle, Hyprlock, Hyprsunset
|
||||
│ ├── walker/ # Application launcher config
|
||||
│ ├── waybar/ # Top bar config and indicators
|
||||
│ ├── mako/ # Notification daemon
|
||||
│ ├── swayosd/ # OSD overlay
|
||||
│ ├── btop/ # System monitor
|
||||
│ └── alacritty/ # Terminal emulator
|
||||
├── default/ # Default/fallback configs and assets
|
||||
│ ├── plymouth/ # Boot splash theme (script, images)
|
||||
│ ├── hypr/ # Default Hyprland settings
|
||||
│ ├── walker/ # Default Walker settings
|
||||
│ └── waybar/ # Default Waybar settings and indicators
|
||||
├── install/ # Installation system (5 phases)
|
||||
│ ├── helpers/ # Shared functions (logging, guards, UI)
|
||||
│ ├── preflight/ # Phase 1: Pre-install checks
|
||||
│ ├── packaging/ # Phase 2: Package installation
|
||||
│ ├── config/ # Phase 3: System configuration
|
||||
│ │ └── hardware/ # Hardware-specific fixes
|
||||
│ ├── login/ # Phase 4: Login/boot setup
|
||||
│ └── post-install/ # Phase 5: Cleanup and reboot
|
||||
├── migrations/ # Timestamped migration scripts
|
||||
├── themes/ # Built-in theme configurations
|
||||
├── .editorconfig
|
||||
├── LICENSE
|
||||
├── README.md
|
||||
├── boot.sh # Boot-time initialization script
|
||||
├── icon.png / icon.txt # Branding assets
|
||||
├── install.sh # Main install entry point
|
||||
├── logo.svg / logo.txt # Branding assets
|
||||
└── version # Current version string
|
||||
```
|
||||
|
||||
## 3. Installation Process
|
||||
|
||||
The installation is orchestrated by `install.sh` which sources five phases sequentially:
|
||||
|
||||
```bash
|
||||
export OMARCHY_PATH="$HOME/.local/share/omarchy"
|
||||
export OMARCHY_INSTALL="$OMARCHY_PATH/install"
|
||||
|
||||
source "$OMARCHY_INSTALL/helpers/all.sh"
|
||||
source "$OMARCHY_INSTALL/preflight/all.sh"
|
||||
source "$OMARCHY_INSTALL/packaging/all.sh"
|
||||
source "$OMARCHY_INSTALL/config/all.sh"
|
||||
source "$OMARCHY_INSTALL/login/all.sh"
|
||||
source "$OMARCHY_INSTALL/post-install/all.sh"
|
||||
```
|
||||
|
||||
### Phase 1: Preflight (`install/preflight/`)
|
||||
|
||||
| Script | Purpose |
|
||||
| :---------------------- | :----------------------------------------------- |
|
||||
| `guard.sh` | Prevent re-running on already installed systems |
|
||||
| `begin.sh` | UI initialization, logo display |
|
||||
| `show-env.sh` | Log environment variables |
|
||||
| `pacman.sh` | Configure pacman repos and mirrors |
|
||||
| `migrations.sh` | Initialize migration tracking |
|
||||
| `first-run-mode.sh` | Set first-run flag |
|
||||
| `disable-mkinitcpio.sh` | Defer mkinitcpio rebuilds during install |
|
||||
|
||||
### Phase 2: Packaging (`install/packaging/`)
|
||||
|
||||
Installs packages in categories:
|
||||
|
||||
| Script | Purpose |
|
||||
| :----------- | :--------------------------------------------------------- |
|
||||
| `base.sh` | Core packages from `omarchy-base.packages` (~150 packages) |
|
||||
| `fonts.sh` | Omarchy custom font for Waybar |
|
||||
| `icons.sh` | Application icons |
|
||||
| `tuis.sh` | TUI application desktop entries |
|
||||
|
||||
The base package list (`install/omarchy-base.packages`) includes:
|
||||
|
||||
- **Desktop:** hyprland, waybar, swaybg, mako, hypridle, hyprlock, hyprsunset, sddm, uwsm
|
||||
- **Terminal:** alacritty, ghostty
|
||||
- **Editor:** neovim (via custom omarchy-nvim package)
|
||||
- **Browser:** chromium (custom omarchy-chromium build)
|
||||
- **Apps:** spotify, typora, obsidian, signal-desktop, libreoffice-fresh, nautilus, evince, mpv
|
||||
- **Dev tools:** docker, docker-compose, lazygit, lazydocker, github-cli, mise, rust, ruby
|
||||
- **Utilities:** btop, fastfetch, ripgrep, fzf, bat, eza, zoxide, dust, jq, gum
|
||||
- **System:** pipewire, wireplumber, power-profiles-daemon, cups, avahi, iwd, ufw
|
||||
- **Fonts:** noto-fonts family, ttf-jetbrains-mono-nerd, ttf-cascadia-mono-nerd, fcitx5
|
||||
- **AUR helper:** yay
|
||||
|
||||
### Phase 3: Configuration (`install/config/`)
|
||||
|
||||
| Script | Purpose |
|
||||
| :------------------------------- | :-------------------------------------------- |
|
||||
| `config.sh` | Deploy dotfiles (3-layer system) |
|
||||
| `theme.sh` | Set default theme |
|
||||
| `branding.sh` | Screensaver and about text |
|
||||
| `git.sh` | Set git user.name/email from install inputs |
|
||||
| `gpg.sh` | GPG agent configuration |
|
||||
| `timezones.sh` | Timezone setup |
|
||||
| `increase-sudo-tries.sh` | More sudo password attempts |
|
||||
| `increase-lockout-limit.sh` | Higher lockout threshold |
|
||||
| `ssh-flakiness.sh` | SSH connection stability tweaks |
|
||||
| `detect-keyboard-layout.sh` | Auto-detect keyboard layout |
|
||||
| `xcompose.sh` | XCompose for special characters |
|
||||
| `mise-work.sh` | mise (dev tool version manager) setup |
|
||||
| `docker.sh` | Docker service and user group |
|
||||
| `mimetypes.sh` | File type associations |
|
||||
| `localdb.sh` | Local database config |
|
||||
| `walker-elephant.sh` | Walker launcher configuration |
|
||||
| `fast-shutdown.sh` | Faster shutdown timeouts |
|
||||
| `sudoless-asdcontrol.sh` | Passwordless ASD control |
|
||||
| `input-group.sh` | Input device permissions |
|
||||
| `omarchy-ai-skill.sh` | AI tool integration |
|
||||
| `powerprofilesctl-rules.sh` | Power profile udev rules |
|
||||
| `wifi-powersave-rules.sh` | Wi-Fi power saving rules |
|
||||
| `hibernation.sh` | Hibernation support |
|
||||
| `fix-powerprofilesctl-shebang.sh`| Shebang fix for power profiles |
|
||||
|
||||
Hardware-specific fixes in `config/hardware/`:
|
||||
|
||||
| Script | Purpose |
|
||||
| :----------------------------- | :-------------------------------------------- |
|
||||
| `network.sh` | Network manager config |
|
||||
| `set-wireless-regdom.sh` | Wireless regulatory domain |
|
||||
| `fix-fkeys.sh` | Function key behavior |
|
||||
| `bluetooth.sh` | Bluetooth service setup |
|
||||
| `printer.sh` | CUPS printing |
|
||||
| `usb-autosuspend.sh` | USB power management |
|
||||
| `ignore-power-button.sh` | Prevent accidental shutdowns |
|
||||
| `legacy-gpu-terminal.sh` | Older GPU terminal support |
|
||||
| `nvidia.sh` | NVIDIA driver configuration |
|
||||
| `fix-f13-amd-audio-input.sh` | Framework 13 AMD audio fix |
|
||||
| `fix-bcm43xx.sh` | Broadcom Wi-Fi fix |
|
||||
| `fix-apple-spi-keyboard.sh` | Apple SPI keyboard |
|
||||
| `fix-apple-suspend-nvme.sh` | Apple NVMe suspend fix |
|
||||
| `fix-apple-t2.sh` | Apple T2 chip support |
|
||||
| `fix-surface-keyboard.sh` | Surface keyboard fix |
|
||||
| `fix-asus-rog-audio-mixer.sh` | ASUS ROG audio fix |
|
||||
| `fix-asus-rog-mic.sh` | ASUS ROG microphone fix |
|
||||
| `fix-yt6801-ethernet-adapter.sh`| YT6801 ethernet driver |
|
||||
| `fix-synaptic-touchpad.sh` | Synaptics touchpad fix |
|
||||
|
||||
### Phase 4: Login (`install/login/`)
|
||||
|
||||
| Script | Purpose |
|
||||
| :------------------ | :--------------------------------------------------- |
|
||||
| `plymouth.sh` | Install Omarchy Plymouth boot splash theme |
|
||||
| `default-keyring.sh`| GNOME keyring auto-unlock setup |
|
||||
| `sddm.sh` | SDDM display manager with auto-login |
|
||||
| `limine-snapper.sh` | Limine bootloader + Snapper snapshot integration |
|
||||
|
||||
SDDM is configured for automatic login:
|
||||
|
||||
```ini
|
||||
[Autologin]
|
||||
User=$USER
|
||||
Session=hyprland-uwsm
|
||||
|
||||
[Theme]
|
||||
Current=breeze
|
||||
```
|
||||
|
||||
### Phase 5: Post-Install (`install/post-install/`)
|
||||
|
||||
| Script | Purpose |
|
||||
| :--------------- | :------------------------------------------------- |
|
||||
| `pacman.sh` | Final pacman cache cleanup and config |
|
||||
| `allow-reboot.sh`| Remove installer sudoers override |
|
||||
| `finished.sh` | Display completion screen, prompt for reboot |
|
||||
|
||||
## 4. Package Management
|
||||
|
||||
Omarchy uses a three-tier package system:
|
||||
|
||||
### 4.1 Pacman (Official Arch Repos)
|
||||
|
||||
The standard Arch package manager. Omarchy's `pacman.conf` adds the custom Omarchy repo:
|
||||
|
||||
```ini
|
||||
[core]
|
||||
Include = /etc/pacman.d/mirrorlist
|
||||
|
||||
[extra]
|
||||
Include = /etc/pacman.d/mirrorlist
|
||||
|
||||
[multilib]
|
||||
Include = /etc/pacman.d/mirrorlist
|
||||
|
||||
[omarchy]
|
||||
SigLevel = Optional TrustAll
|
||||
Server = https://pkgs.omarchy.org/stable/$arch
|
||||
```
|
||||
|
||||
### 4.2 OPR (Omarchy Package Repository)
|
||||
|
||||
Custom packages built and hosted by the Omarchy team via the `omarchy-pkgs` repo. These include:
|
||||
|
||||
- `omarchy-nvim` -- Bundled Neovim configuration
|
||||
- `omarchy-walker` -- Pre-configured Walker launcher
|
||||
- `omarchy-chromium` -- Custom Chromium with live theme switching
|
||||
- `omarchy-zsh` / `omarchy-fish` -- Shell configurations
|
||||
|
||||
The package build system (`omarchy-pkgs`) uses three tiers:
|
||||
|
||||
| Tier | Build Frequency | Deployment | Review |
|
||||
| :------- | :----------------- | :------------------ | :--------- |
|
||||
| Stable | Manual | Stable repo only | Manual |
|
||||
| Edge | Daily (6:00 AM UTC)| Edge repo only | PR review |
|
||||
| Shared | Every 6 hours | Both repos | Auto-merge |
|
||||
|
||||
Multi-architecture: x86_64 (native) and aarch64 (QEMU-emulated).
|
||||
|
||||
### 4.3 AUR (Arch User Repository)
|
||||
|
||||
Community packages installed via `yay`. The `omarchy-pkg-aur-add` script wraps yay:
|
||||
|
||||
```bash
|
||||
if omarchy-pkg-missing "$@"; then
|
||||
yay -S --noconfirm --needed "$@" || exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### 4.4 Omarchy Mirror
|
||||
|
||||
A dedicated mirror of Arch core/extra/multilib repos hosted on Cloudflare R2:
|
||||
|
||||
- **Stable:** `https://stable-mirror.omarchy.org/` -- runs ~1 month behind latest
|
||||
- **Edge:** `https://mirror.omarchy.org/` -- tracks latest Arch repos hourly
|
||||
|
||||
## 5. Desktop Environment Stack
|
||||
|
||||
### 5.1 Compositor: Hyprland
|
||||
|
||||
Hyprland is the Wayland compositor and tiling window manager. It's launched via UWSM (Universal Wayland
|
||||
Session Manager) through SDDM. Key configuration files:
|
||||
|
||||
- `~/.config/hypr/hyprland.conf` -- Main config (sources others)
|
||||
- `~/.config/hypr/bindings.conf` -- User key bindings
|
||||
- `~/.config/hypr/monitors.conf` -- Monitor layout
|
||||
- `~/.config/hypr/input.conf` -- Input device settings
|
||||
- `~/.config/hypr/looknfeel.conf` -- Theme visual settings
|
||||
|
||||
Key bindings (Super = primary modifier):
|
||||
|
||||
| Binding | Action |
|
||||
| :--------------------- | :------------------------ |
|
||||
| `Super + Return` | Terminal |
|
||||
| `Super + Space` | Application launcher |
|
||||
| `Super + Alt + Space` | Omarchy menu |
|
||||
| `Super + W` | Close window |
|
||||
| `Super + F` | Fullscreen |
|
||||
| `Super + Arrow` | Navigate windows |
|
||||
| `Super + Shift + B` | Browser |
|
||||
| `Super + Shift + N` | Editor (Neovim) |
|
||||
| `Super + Shift + F` | File manager (Nautilus) |
|
||||
| `Super + Shift + M` | Music (Spotify) |
|
||||
| `Super + K` | Show all keybindings |
|
||||
| `Super + Ctrl + E` | Emoji picker |
|
||||
|
||||
### 5.2 Top Bar: Waybar
|
||||
|
||||
Waybar provides the status bar at the top of the screen. Configured in `config/waybar/config.jsonc`:
|
||||
|
||||
```
|
||||
modules-left: [custom/omarchy, hyprland/workspaces]
|
||||
modules-center: [clock, custom/update, custom/voxtype, custom/screenrecording-indicator]
|
||||
modules-right: [group/tray-expander, bluetooth, network, pulseaudio, cpu, battery]
|
||||
```
|
||||
|
||||
The Omarchy logo button in the top-left opens the Omarchy menu.
|
||||
|
||||
### 5.3 Application Launcher: Walker
|
||||
|
||||
Walker is the application launcher, opened with `Super + Space`. It provides fuzzy search across
|
||||
applications, files, and commands.
|
||||
|
||||
### 5.4 Notifications: Mako
|
||||
|
||||
Mako handles desktop notifications with theme-aware styling.
|
||||
|
||||
### 5.5 OSD: SwayOSD
|
||||
|
||||
SwayOSD provides on-screen display for volume, brightness, and caps lock changes.
|
||||
|
||||
### 5.6 Terminal: Ghostty / Alacritty
|
||||
|
||||
Ghostty is the default terminal. Alacritty is also pre-installed. Users can install Kitty as well.
|
||||
|
||||
### 5.7 Editor: Neovim
|
||||
|
||||
Custom `omarchy-nvim` package with a pre-configured setup including LSP, Treesitter, and the
|
||||
pixel.nvim colorscheme (adapts to terminal ANSI colors).
|
||||
|
||||
### 5.8 Lock Screen: Hyprlock
|
||||
|
||||
Hyprlock provides the lock screen with theme-aware styling and optional blurred background.
|
||||
|
||||
### 5.9 Idle Management: Hypridle
|
||||
|
||||
Hypridle manages screen dimming, locking, and suspend after configurable idle timeouts.
|
||||
|
||||
### 5.10 Night Light: Hyprsunset
|
||||
|
||||
Hyprsunset provides blue light filtering (night mode).
|
||||
|
||||
### 5.11 Omarchy Menu
|
||||
|
||||
A comprehensive shell script (`bin/omarchy-menu`) providing a hierarchical menu system via Walker:
|
||||
|
||||
```
|
||||
Main Menu
|
||||
├── Apps (Walker launcher)
|
||||
├── Learn (keybindings reference)
|
||||
├── Trigger (screenshot, screenrecord, share)
|
||||
├── Style (theme, font, background)
|
||||
├── Setup (audio, wifi, bluetooth, power, monitors, DNS, security, config)
|
||||
├── Install (packages, AUR, web apps, TUIs, dev environments, editors, AI tools, gaming)
|
||||
├── Remove (packages, web apps, dev environments, preinstalls)
|
||||
├── Update (Omarchy, channel, config, themes, processes, hardware, firmware, password)
|
||||
├── About (fastfetch system info)
|
||||
└── System (lock, screensaver, suspend, hibernate, restart, shutdown)
|
||||
```
|
||||
|
||||
## 6. Configuration / Dotfiles System
|
||||
|
||||
Omarchy uses a 3-layer configuration system with increasing priority:
|
||||
|
||||
### Layer 1: Default (lowest priority)
|
||||
|
||||
Located in `~/.local/share/omarchy/default/`. These are the factory defaults shipped with Omarchy.
|
||||
Users should never edit these directly. They are overwritten on every update.
|
||||
|
||||
### Layer 2: Theme
|
||||
|
||||
Located in `~/.local/share/omarchy/themes/<theme-name>/`. When a theme is activated, its config files
|
||||
override the defaults. Theme files cover: Hyprland, Hyprlock, Alacritty, Neovim, btop, Mako, Waybar,
|
||||
Walker, SwayOSD, and backgrounds.
|
||||
|
||||
### Layer 3: User (highest priority)
|
||||
|
||||
Located in `~/.config/`. User edits here take ultimate precedence. Files include:
|
||||
|
||||
- `~/.config/hypr/bindings.conf` -- Custom keybindings
|
||||
- `~/.config/hypr/input.conf` -- Input settings
|
||||
- `~/.config/hypr/monitors.conf` -- Monitor layout
|
||||
- `~/.config/hypr/looknfeel.conf` -- Visual overrides
|
||||
- `~/.config/omarchy/hooks/` -- User hook scripts
|
||||
- `~/.config/omarchy/extensions/menu.sh` -- Menu extensions
|
||||
|
||||
The `config.sh` install script deploys this layered system. The `omarchy-refresh-*` commands can
|
||||
reset specific configs back to defaults.
|
||||
|
||||
### Hooks
|
||||
|
||||
Users can place scripts in `~/.config/omarchy/hooks/` to run at specific events. The `omarchy-hook`
|
||||
script dispatches named hooks:
|
||||
|
||||
```bash
|
||||
HOOK_PATH="$HOME/.config/omarchy/hooks/$1"
|
||||
if [[ -f $HOOK_PATH ]]; then
|
||||
bash "$HOOK_PATH" "$@"
|
||||
fi
|
||||
```
|
||||
|
||||
## 7. Theming System
|
||||
|
||||
Omarchy ships with 14 built-in themes. Each theme is a collection of config files that atomically restyle
|
||||
every themed component:
|
||||
|
||||
| Component | Config File |
|
||||
| :------------- | :----------------------- |
|
||||
| Alacritty | `alacritty.toml` |
|
||||
| btop | `btop.theme` |
|
||||
| Hyprland | `hyprland.conf` |
|
||||
| Hyprlock | `hyprlock.conf` |
|
||||
| Mako | `mako.ini` |
|
||||
| Neovim | `neovim.lua` |
|
||||
| SwayOSD | `swayosd.css` |
|
||||
| Walker | `walker.css` |
|
||||
| Waybar | `waybar.css` |
|
||||
| Backgrounds | `backgrounds/` directory |
|
||||
|
||||
### Theme Management
|
||||
|
||||
- **Switch theme:** `omarchy-theme-set <name>` or via the Style menu
|
||||
- **Install extra theme:** `omarchy-theme-install <git-url>`
|
||||
- **Remove theme:** `omarchy-theme-remove`
|
||||
- **Update themes:** `omarchy-theme-update`
|
||||
- **Browse themes:** Walker menu with visual previews
|
||||
- **Cycle background:** `omarchy-theme-bg-next`
|
||||
|
||||
The Neovim colorscheme (`pixel.nvim`) dynamically adapts to terminal ANSI colors (0-15), meaning theme
|
||||
changes in the terminal automatically propagate to the editor without any Neovim-specific theme logic.
|
||||
|
||||
Custom Chromium build (`omarchy-chromium`) supports live Material Design 3 theme switching without
|
||||
restarting the browser.
|
||||
|
||||
### Community Themes
|
||||
|
||||
Third-party themes can be installed from any Git repository. Example:
|
||||
`omarchy-theme-install https://github.com/omacom-io/omarchy-synthwave84-theme.git`
|
||||
|
||||
## 8. Boot Management
|
||||
|
||||
### 8.1 Limine Bootloader
|
||||
|
||||
Omarchy uses Limine as its bootloader (not GRUB). Limine is configured to integrate with Snapper
|
||||
for bootable snapshot entries.
|
||||
|
||||
### 8.2 Plymouth Boot Splash
|
||||
|
||||
A custom Plymouth theme displays the Omarchy logo during boot with a progress bar animation. The
|
||||
theme uses a Tokyo Night color scheme (dark background: `rgb(26, 27, 38)`).
|
||||
|
||||
During boot:
|
||||
1. LUKS encryption password prompt appears over the Omarchy logo
|
||||
2. After password entry, a progress bar animates (fake progress with easing curve to 70%, then real
|
||||
boot progress takes over)
|
||||
3. On completion, SDDM auto-logs into Hyprland
|
||||
|
||||
### 8.3 Snapper Snapshots
|
||||
|
||||
Btrfs snapshots are managed by Snapper with these limits:
|
||||
|
||||
- Maximum 30% of filesystem space for snapshots (`SPACE_LIMIT=0.3`)
|
||||
- Minimum 30% free space maintained (`FREE_LIMIT=0.3`)
|
||||
- Maximum 5 snapshots retained (`NUMBER_LIMIT=5`)
|
||||
|
||||
Snapshots are created automatically on every `omarchy-update`. Users can also create manual snapshots
|
||||
with `omarchy-snapshot create`.
|
||||
|
||||
To restore: select a snapshot from the Limine boot menu, choosing by date and version.
|
||||
|
||||
## 9. Security
|
||||
|
||||
| Feature | Implementation |
|
||||
| :-------------------- | :--------------------------------------------------- |
|
||||
| Disk encryption | LUKS (mandatory during install) |
|
||||
| Firewall | UFW (enabled by default) |
|
||||
| GPG | GPG agent configured for signing |
|
||||
| Keyring | GNOME keyring auto-unlocked on login |
|
||||
| SSH | Connection stability tweaks |
|
||||
| Fingerprint | Optional fprintd setup via `omarchy-setup-fingerprint` |
|
||||
| FIDO2 | Optional FIDO2 key setup via `omarchy-setup-fido2` |
|
||||
| Sudo | Increased retry limits, configurable lockout |
|
||||
| No Secure Boot | Explicitly not supported (Microsoft ecosystem) |
|
||||
|
||||
## 10. Migration System
|
||||
|
||||
Omarchy uses timestamped migration scripts in the `migrations/` directory. Each migration is a shell
|
||||
script named with a Unix timestamp (e.g., `1757861484.sh`). Migrations run automatically during
|
||||
`omarchy-update` via `install/preflight/migrations.sh`.
|
||||
|
||||
Example migration:
|
||||
|
||||
```bash
|
||||
echo "Add a blurred background to the lock screen"
|
||||
omarchy-refresh-hyprlock
|
||||
```
|
||||
|
||||
Migrations are tracked so they only run once per system. This allows Omarchy to evolve its configuration
|
||||
over time without users needing to manually apply changes.
|
||||
|
||||
## 11. Update System
|
||||
|
||||
### Update Channels
|
||||
|
||||
Four update channels with different stability levels:
|
||||
|
||||
| Channel | Description |
|
||||
| :------ | :---------------------------------- |
|
||||
| Stable | Default. Mirrors ~1 month behind |
|
||||
| RC | Release candidates |
|
||||
| Edge | Latest packages, daily builds |
|
||||
| Dev | Development branch |
|
||||
|
||||
Switch channels via `omarchy-channel-set <channel>` or the Omarchy menu.
|
||||
|
||||
### Update Process (`omarchy-update`)
|
||||
|
||||
1. Create a Btrfs snapshot (if Snapper is available)
|
||||
2. Pull latest Omarchy from git
|
||||
3. Run pending migrations
|
||||
4. Execute the install pipeline (re-runs all phases idempotently)
|
||||
5. Display update notification in Waybar
|
||||
|
||||
Waybar checks for updates every 6 hours and shows a notification icon.
|
||||
|
||||
## 12. ISO Generation
|
||||
|
||||
The ISO is built using the `omarchy-iso` repo (`omacom-io/omarchy-iso`).
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
omacom-io/omarchy-iso/
|
||||
├── archiso/ # Git submodule: gitlab.archlinux.org/archlinux/archiso.git
|
||||
├── bin/ # Build and release scripts
|
||||
│ ├── omarchy-iso-make # Build the ISO
|
||||
│ ├── omarchy-iso-boot # Test via QEMU VM
|
||||
│ ├── omarchy-iso-sign # GPG sign the ISO
|
||||
│ ├── omarchy-iso-upload # Upload to Cloudflare R2
|
||||
│ └── omarchy-iso-release # Full build→sign→upload pipeline
|
||||
├── builder/ # Build helpers and configs
|
||||
└── configs/ # archiso profile configuration
|
||||
├── airootfs/ # Files overlaid onto the live system
|
||||
│ ├── etc/ # System configs (mkinitcpio, Plymouth, pacman)
|
||||
│ └── root/ # Automated install script
|
||||
├── efiboot/ # EFI boot loader entries
|
||||
├── grub/ # GRUB config (for ISO boot)
|
||||
└── syslinux/ # Syslinux config (legacy BIOS)
|
||||
```
|
||||
|
||||
### ISO Build Process
|
||||
|
||||
1. The `archiso` submodule provides the ISO creation framework
|
||||
2. `omarchy-iso-make` wraps archiso's `mkarchiso` command
|
||||
3. The profile in `configs/` defines what goes into the ISO:
|
||||
- Base packages from `omarchy-other.packages` (base, base-devel, drivers, audio stack)
|
||||
- Omarchy repo packages from `omarchy-base.packages`
|
||||
- Plymouth with Omarchy theme
|
||||
- Automated installer script
|
||||
4. The ISO includes offline package mirrors (no internet needed during install)
|
||||
|
||||
### Automated Install Script
|
||||
|
||||
`configs/airootfs/root/.automated_script.sh` runs on first boot from the ISO (on `/dev/tty1`):
|
||||
|
||||
1. `use_omarchy_helpers()` -- Set up environment and source helpers
|
||||
2. `run_configurator()` -- Launch the Omarchy Configurator (user credentials, disk selection)
|
||||
3. `install_arch()` -- Run `archinstall` with the configured settings (base system, partitioning,
|
||||
LUKS encryption, Btrfs, user creation)
|
||||
4. `install_omarchy()` -- Chroot into the new system and run `install.sh`
|
||||
5. Reboot into the installed system
|
||||
|
||||
### Configurable Build
|
||||
|
||||
The ISO build supports:
|
||||
- `OMARCHY_INSTALLER_REPO` -- default: `basecamp/omarchy`
|
||||
- `OMARCHY_INSTALLER_REF` -- default: `master`
|
||||
- `--local-source` -- build from local repo copy
|
||||
- `--dev` -- build development ISO
|
||||
|
||||
### Distribution
|
||||
|
||||
ISOs are GPG-signed and uploaded to Cloudflare R2 via rclone. The `omarchy-iso-release` script
|
||||
runs the full pipeline: build → sign → upload.
|
||||
|
||||
## 13. omacom-io Ecosystem
|
||||
|
||||
The [omacom-io](https://github.com/omacom-io) GitHub organization maintains 20 repositories.
|
||||
|
||||
### Core Infrastructure
|
||||
|
||||
| Repository | Stars | Description |
|
||||
| :------------------ | ----: | :------------------------------------------------------- |
|
||||
| `omarchy-iso` | 176 | ISO builder wrapping archiso |
|
||||
| `omarchy-pkgs` | 13 | Package build system (PKGBUILDs, signing, sync) |
|
||||
| `omarchy-mirror` | 3 | Arch repo mirror on Cloudflare R2 (stable + edge) |
|
||||
| `omarchy-chromium` | 26 | Custom Chromium with live theme switching (0BSD license) |
|
||||
|
||||
### Shell & Editor
|
||||
|
||||
| Repository | Stars | Description |
|
||||
| :------------------ | ----: | :------------------------------------------------------- |
|
||||
| `omarchy-zsh` | 43 | Zsh config with fzf, starship, eza, zoxide |
|
||||
| `omarchy-fish` | 33 | Fish config with fzf.fish, starship, eza, zoxide |
|
||||
| `pixel.nvim` | 2 | Terminal ANSI color-adaptive Neovim colorscheme (fork) |
|
||||
|
||||
### Themes
|
||||
|
||||
| Repository | Stars | Description |
|
||||
| :---------------------------- | ----: | :--------------------------------------- |
|
||||
| `omarchy-synthwave84-theme` | 26 | Example community-style theme |
|
||||
|
||||
### Sibling Products
|
||||
|
||||
| Repository | Stars | Description |
|
||||
| :------------ | ----: | :--------------------------------------------------------- |
|
||||
| `omaterm` | 26 | Headless/terminal-only Arch setup (no GUI) |
|
||||
| `omamac` | 17 | macOS setup mimicking Omarchy workflow |
|
||||
| `omadots` | 10 | Shared dotfiles across Omarchy, Omaterm, Omamac |
|
||||
|
||||
### Websites
|
||||
|
||||
| Repository | Stars | URL |
|
||||
| :-------------- | ----: | :--------------------- |
|
||||
| `omarchy-site` | 10 | omarchy.org |
|
||||
| `omaterm-site` | 8 | omaterm.org |
|
||||
| `omamac-site` | 3 | omamac.org |
|
||||
| `website` | 2 | omacom.io |
|
||||
| `omacon` | 18 | Conference landing page |
|
||||
|
||||
### Archived
|
||||
|
||||
| Repository | Note |
|
||||
| :---------------------- | :------------------------------------------ |
|
||||
| `omarchy-configurator` | Rolled into omarchy-iso |
|
||||
| `omarchy-lazyvim` | Superseded by omarchy-nvim |
|
||||
| `asdcontrol-git` | ASD control package build |
|
||||
|
||||
### Notable Community Projects
|
||||
|
||||
| Repository | Stars | Description |
|
||||
| :------------------------------- | ----: | :--------------------------------------- |
|
||||
| `goodroot/hyprwhspr` | 809 | Native speech-to-text for Linux |
|
||||
| `henrysipp/omarchy-nix` | 657 | Omarchy ported to NixOS |
|
||||
| `malik-na/omarchy-mac` | 530 | Omarchy for Apple Silicon Macs |
|
||||
| `devmobasa/wayscriber` | 430 | Live annotation overlay for Wayland |
|
||||
| `erans/hyprmon` | 385 | TUI monitor config for Hyprland |
|
||||
| `bjarneo/aether` | 346 | Easy Omarchy theme creator |
|
||||
| `aorumbayev/awesome-omarchy` | 259 | Curated list of Omarchy resources |
|
||||
| `elpritchos/omadora` | 70 | Minimal Fedora + Hyprland (Omarchy-like) |
|
||||
|
||||
## 14. Arch to Debian Mapping
|
||||
|
||||
This section maps Omarchy's Arch-specific components to their Debian equivalents for the Yino port.
|
||||
|
||||
### Package Management
|
||||
|
||||
| Arch (Omarchy) | Debian (Yino) | Notes |
|
||||
| :-------------------------------- | :----------------------------------- | :--------------------------------- |
|
||||
| `pacman` | `apt` | Core package manager |
|
||||
| `pacman.conf` + repos | `sources.list` + repos | Repository configuration |
|
||||
| `yay` (AUR helper) | N/A or build from source | No AUR equivalent; use custom .deb repo, PPAs, or Flatpak |
|
||||
| OPR (`pkgs.omarchy.org`) | Custom APT repo | Need to build .deb packages |
|
||||
| `omarchy-pkgs` (PKGBUILD system) | .deb packaging (dpkg-buildpackage) | Build system needs rewrite |
|
||||
| `omarchy-mirror` (Arch mirror) | Debian mirror / snapshot.debian.org | Debian is already stable |
|
||||
| `pacman -S --needed` | `apt install` | Idempotent install |
|
||||
| `pacman -Q` | `dpkg -l` / `apt list --installed` | Query installed packages |
|
||||
|
||||
### Boot & Init
|
||||
|
||||
| Arch (Omarchy) | Debian (Yino) | Notes |
|
||||
| :------------------------ | :-------------------------------- | :--------------------------------- |
|
||||
| `archinstall` | `debian-installer` / `preseed` | Automated installation |
|
||||
| `archiso` (ISO framework) | `live-build` or `simple-cdd` | ISO generation |
|
||||
| `mkinitcpio` | `initramfs-tools` or `dracut` | Initramfs generation |
|
||||
| Limine bootloader | GRUB2 or systemd-boot | Consider: Limine works on Debian too |
|
||||
| `mkinitcpio.conf` hooks | `initramfs-tools` hooks/scripts | Different hook system |
|
||||
| Plymouth | Plymouth | Same -- available in Debian |
|
||||
| Snapper | Snapper | Same -- available in Debian |
|
||||
| SDDM | SDDM | Same -- available in Debian |
|
||||
|
||||
### Desktop Environment
|
||||
|
||||
| Arch (Omarchy) | Debian (Yino) | Notes |
|
||||
| :-------------------- | :---------------------------- | :----------------------------------------- |
|
||||
| Hyprland | Hyprland | Not in Debian stable; needs backport/build |
|
||||
| Waybar | Waybar | Available in Debian, may need newer version |
|
||||
| Walker | Walker | Needs manual build/packaging |
|
||||
| Mako | Mako | Available in Debian |
|
||||
| SwayOSD | SwayOSD | Needs manual build/packaging |
|
||||
| Hypridle | Hypridle | Needs manual build/packaging |
|
||||
| Hyprlock | Hyprlock | Needs manual build/packaging |
|
||||
| Hyprsunset | Hyprsunset | Needs manual build/packaging |
|
||||
| UWSM | UWSM | Needs manual build/packaging |
|
||||
|
||||
### Applications
|
||||
|
||||
| Arch (Omarchy) | Debian (Yino) | Notes |
|
||||
| :----------------------- | :-------------------------- | :----------------------------------------- |
|
||||
| Ghostty | Ghostty | Needs manual build/packaging |
|
||||
| Alacritty | Alacritty | Available in Debian |
|
||||
| Neovim | Neovim | Available; may need newer version |
|
||||
| Chromium | Chromium | Available; omarchy-chromium needs rebuild |
|
||||
| Nautilus | Nautilus | Available in Debian |
|
||||
| Spotify | Spotify | Snap/Flatpak or official .deb |
|
||||
| 1Password | 1Password | Official .deb available |
|
||||
| Docker | Docker | Official .deb repo available |
|
||||
| mise | mise | Install script or manual build |
|
||||
|
||||
### System Utilities
|
||||
|
||||
| Arch (Omarchy) | Debian (Yino) | Notes |
|
||||
| :--------------- | :----------------- | :----------------------------------------------- |
|
||||
| `gum` | `gum` | Needs manual install (Go binary) |
|
||||
| `tte` | `tte` | Needs manual install (`tte-go` in omacom-io) |
|
||||
| `fzf` | `fzf` | Available in Debian |
|
||||
| `bat` | `bat` | Available in Debian (may be named `batcat`) |
|
||||
| `eza` | `eza` | Needs manual install or cargo |
|
||||
| `zoxide` | `zoxide` | Available in newer Debian or manual install |
|
||||
| `ripgrep` | `ripgrep` | Available in Debian |
|
||||
| `dust` | `dust` | Needs manual install or cargo |
|
||||
| `lazygit` | `lazygit` | Needs manual install (Go binary) |
|
||||
| `lazydocker` | `lazydocker` | Needs manual install (Go binary) |
|
||||
| `fastfetch` | `fastfetch` | Available in newer Debian or manual build |
|
||||
| `btop` | `btop` | Available in Debian |
|
||||
| `ufw` | `ufw` | Available in Debian |
|
||||
|
||||
### Things to Remove / Simplify for Yino
|
||||
|
||||
Since Debian is a stable release (not rolling), several Omarchy mechanisms become unnecessary or simpler:
|
||||
|
||||
| Omarchy Feature | Yino Approach |
|
||||
| :--------------------------- | :------------------------------------------------------- |
|
||||
| Arch mirror with 1-month lag | Not needed -- Debian stable is already conservative |
|
||||
| `disable-mkinitcpio.sh` | Not needed -- Debian uses initramfs-tools |
|
||||
| Edge/Dev update channels | Simpler: just stable + backports |
|
||||
| Frequent migrations | Fewer needed -- stable base changes less |
|
||||
| AUR | Not applicable -- use custom .deb repo or Flatpak |
|
||||
| `omarchy-pkgs` build system | Rewrite for .deb packaging if custom packages are needed |
|
||||
| Apple T2 support | Optional -- evaluate if needed for target hardware |
|
||||
| NVIDIA-specific fixes | Keep but adapt for Debian's nvidia packaging |
|
||||
|
||||
### Key Porting Challenges
|
||||
|
||||
1. **Hyprland and related tools** -- Not in Debian stable; need to either:
|
||||
- Build from source and package as .deb
|
||||
- Use a PPA or third-party repo
|
||||
- Backport from Debian unstable/experimental
|
||||
|
||||
2. **ISO generation** -- Replace `archiso` with `live-build` or `simple-cdd`; rewrite the automated
|
||||
installer to use `debian-installer` with preseed or a custom script
|
||||
|
||||
3. **Package repository** -- Replace PKGBUILD-based `omarchy-pkgs` with .deb packaging if custom
|
||||
packages are needed
|
||||
|
||||
4. **Walker** -- Not packaged for Debian; needs manual build
|
||||
|
||||
5. **Ghostty** -- Not packaged for Debian; needs manual build
|
||||
|
||||
6. **omarchy-chromium** -- Significant effort to rebuild custom Chromium for Debian; consider whether
|
||||
the live theme switching is worth the build complexity, or use standard Chromium
|
||||
Loading…
x
Reference in New Issue
Block a user