Moonarch

Reproducible Arch Linux desktop environment — fully automated from bare metal to a configured Niri (scrollable tiling Wayland) system with Catppuccin Mocha theming.

Moonarch combines archinstall for the base system with post-install automation that handles packages, XDG defaults, system services, greeter, idle management, and a Walker launcher with native providers and dmenu-based helper scripts. The result is a complete development/productivity desktop that can be rebuilt from scratch in minutes.

Why These Choices

Component	Choice	Why
Compositor	Niri	Scrollable tiling — no fixed grid, infinite horizontal workspace. Purpose-built Wayland compositor, not an X11 port.
Greeter	greetd + moongreet	Minimal, Wayland-native login. moongreet provides GTK4 UI with fingerprint support, running inside its own Niri instance.
Lock Screen	moonlock	ext-session-lock-v1 protocol — compositor guarantees lock on crash. PAM + fprintd, GPU blur, multi-monitor.
Power Menu	moonset	GTK4 Layer Shell overlay above Waybar. Lock, logout, hibernate, reboot, shutdown with confirmation.
Idle Manager	stasis	Separate AC/battery power plans. Brightness dimming, DPMS, lock (via moonlock), and suspend on configurable timeouts.
Bar	Waybar	Wayland-native, highly customizable. Niri workspace/window modules via community plugins.
Launcher	Walker + Elephant	Wayland-native GTK4 launcher with built-in providers for apps, clipboard, bluetooth, audio, files, and calculator. Dmenu mode for custom scripts (VPN, CPU governor).
Terminal	Foot	Fast, minimal Wayland-native terminal. Server mode for instant window spawning.
Shell	Zsh	Programmable completion, FZF integration, syntax highlighting.
Audio	PipeWire	Drop-in replacement for PulseAudio/JACK with lower latency. RNNoise input denoising configured out of the box.
Display Management	kanshi + wdisplays	kanshi auto-switches output profiles on hotplug. wdisplays for manual GUI configuration.
Notifications	dunst	Lightweight, scriptable. DND mode exposed as Waybar module.
Clipboard	Walker clipboard provider	Built-in clipboard history with image support. Managed by Elephant backend.
GTK Theme	Colloid-Grey-Dark-Catppuccin	Catppuccin Mocha palette, grey accent, explicit dark variant.
Icons	Colloid-Grey-Catppuccin-Dark	Catppuccin-colored icon set matching the GTK theme.
Cursor	Sweet-cursors	Visible on dark backgrounds without clashing.
Font	UbuntuSans Nerd Font	Clean sans-serif with full Nerd Font glyph coverage for bar/terminal icons.
Wallpaper	waypaper + awww	waypaper provides GUI selection, awww handles animated transitions (60 FPS, 2s crossfade).
Firewall	UFW	Simple deny-incoming/allow-outgoing default. Sane baseline without iptables complexity.
AUR Helper	paru	Rust-based, pacman-compatible. Supports custom PKGBUILD repos for moongreet/moonlock/moonset.

Quick Start

Fresh Install (Bare Metal)

1. Boot the Arch ISO and download the config:

   curl -O https://gitea.moonarch.de/nevaforget/moonarch/raw/branch/main/config/user_configuration.json
   archinstall --config user_configuration.json
   

2. Choose disk and kernel interactively — everything else comes from the config.
3. Reboot, log in, then:

   /opt/moonarch/scripts/post-install.sh
   

4. Reboot again — done.

The archinstall config clones this repo to /opt/moonarch via custom-commands. post-install.sh handles the remaining ~100 packages, all configs, themes, services, and user setup.

Transform (Existing Arch+Wayland System)

Already running Arch with a Wayland compositor (Sway, Hyprland, GNOME Wayland, etc.)? Transform converts your system to Moonarch without reinstalling.

Prerequisites: Active Wayland session, git installed.

# Clone the repo
sudo git clone https://gitea.moonarch.de/nevaforget/moonarch.git /opt/moonarch

# Preview what will happen (no changes made)
/opt/moonarch/scripts/transform.sh --dry-run

# Run the transform
/opt/moonarch/scripts/transform.sh

# Reboot (do NOT log out — your previous DM is already disabled)
sudo reboot

The script will:

1. Show a pre-flight summary (package diff, config changes, detected conflicts)
2. Back up your ~/.config/, ~/.zshrc, and /etc/xdg/ to timestamped tar archives
3. Disable conflicting display managers (SDDM, GDM, LightDM, etc.)
4. Remove conflicting packages (e.g. PulseAudio → PipeWire)
5. Install all Moonarch packages and configs (hard overwrite of all user configs)
6. Enable greetd, firewall, and system services

Update

moonarch-update

Interactive updater that syncs the repo, upgrades system/AUR packages, reconciles package lists against what's installed, deploys changed XDG defaults, and cleans orphaned packages.

Project Structure

config/
  user_configuration.json       archinstall config (locale, audio, services, custom-commands)

packages/
  official.txt                  Arch repo packages (~100), one per line
  aur.txt                       AUR packages (~15), one per line

scripts/
  lib.sh                        Shared helpers sourced by all scripts
  post-install.sh               Main automation (packages, configs, themes, services)
  transform.sh                  Convert existing Arch+Wayland system to Moonarch
  install-themes.sh             Cursor theme installer (Sweet-cursors)
  update.sh                     System updater (symlinked to moonarch-update)

defaults/
  xdg/                          System-wide XDG configs (deployed to /etc/xdg/)
    niri/config.kdl               Compositor: layout, keybinds, startup apps
    waybar/config, style.css      Bar: modules, layout, Catppuccin styling
    walker/config.toml, themes/   Launcher: Walker config + gtk-inherit theme
    foot/foot.ini                 Terminal: font, colors, keybinds
    dunst/dunstrc                 Notifications: geometry, colors, behavior
    kanshi/config                 Display profiles (empty, user-configured)
    gtklock/                      Lock screen: config, UI layout, CSS
    stasis/stasis.rune            Idle manager: AC/battery power plans
    pipewire/                     Audio: RNNoise input denoising
    waypaper/config.ini           Wallpaper manager: backend, folder, transitions
    fastfetch/config.jsonc        System info display
    gtk-3.0/, gtk-4.0/           GTK theme settings

  bin/                          Helper scripts (deployed to /usr/local/bin/)
    moonarch-sink-switcher        Audio output switcher (walker dmenu + pactl)
    moonarch-vpn                  VPN connection manager (walker dmenu + nmcli)
    moonarch-cpugov               CPU governor switcher (walker dmenu + auto-cpufreq)
    moonarch-dnd                  Dunst Do Not Disturb toggle (Waybar JSON output)
    moonarch-btnote               Bluetooth device battery monitor (upower + notify-send)
    moonarch-capsnote             Caps Lock toggle notification
    moonarch-waybar-cpugov        Waybar module: CPU governor status
    moonarch-waybar-gpustat       Waybar module: GPU utilization
    moonarch-waybar-hidpp         Waybar module: Logitech HID++ device battery

  shell/zshrc                   Zsh config: prompt, aliases, FZF, completion
  etc/greetd/                   greetd daemon + greeter Niri config
  etc/moongreet/                moongreet configuration
  user/systemd/user/             Systemd user services (kanshi, walker, elephant)
  user/waybar/                  Per-user Waybar overrides (only copied if missing)
  backgrounds/wallpaper.jpg     Default wallpaper (shared by desktop, greeter, lock screen)

Startup Sequence

greetd ─► niri (greeter instance) ─► moongreet ─► user authenticates
                                                         │
                                                         ▼
                                                   niri (user session)
                                                         │
                           ┌──────────┬────────┬────────┬──────────┐
                           ▼          ▼        ▼        ▼          ▼
                        waybar      dunst   foot     waypaper   cliphist
                        (bar)    (notify) (server)  (wallpaper) (clipboard)

                        kanshi runs as a systemd user service (graphical-session.target)

Keybinds (Default)

Key	Action
Super+Return	Open terminal (foot)
Super+Space	App launcher (walker)
Super+Q	Close window
Super+O / Super+Tab	Overview
Super+F	Maximize column
Super+Shift+F	Fullscreen window
Super+V	Toggle floating
Super+H/J/K/L	Focus left/down/up/right
Super+Ctrl+H/J/K/L	Move window
Super+Shift+H/J/K/L	Focus monitor
Super+1-9	Switch workspace
Super+C	Clipboard history
Super+E	File manager
Super+A	Audio control (walker)
Super+N	VPN manager
Super+Alt+L	Session menu (wlogout)
Print	Screenshot
Ctrl+Print	Screenshot screen
Alt+Print	Screenshot window

Customization

All system configs live in /etc/xdg/ and can be overridden per-user in ~/.config/:

Component	System Default	User Override
Niri	/etc/xdg/niri/config.kdl	~/.config/niri/config.kdl
Waybar	/etc/xdg/waybar/	~/.config/waybar/
Walker	/etc/xdg/walker/	~/.config/walker/
Foot	/etc/xdg/foot/foot.ini	~/.config/foot/foot.ini
Dunst	/etc/xdg/dunst/dunstrc	~/.config/dunst/dunstrc
kanshi	/etc/xdg/kanshi/config	~/.config/kanshi/config
PipeWire	/etc/xdg/pipewire/	~/.config/pipewire/
Zsh	/etc/zsh/zshrc.moonarch	~/.zshrc + ~/.zshrc.d/

Helper scripts in /usr/local/bin/moonarch-* are not meant to be overridden — they are part of the system and updated via moonarch-update.

System Services

Service	Purpose
greetd	Login greeter (runs moongreet inside Niri)
NetworkManager	Network management (WiFi, VPN, Ethernet)
bluetooth	Bluetooth stack (bluez)
docker	Container runtime
systemd-timesyncd	NTP time synchronization
ufw	Firewall (deny incoming, allow outgoing)
auto-cpufreq	CPU frequency scaling (AC: performance, battery: powersave)

User Services (systemd --user)

Service	Purpose
kanshi	Dynamic display configuration (auto-switch output profiles on hotplug)
elephant	Walker data provider backend (apps, clipboard, bluetooth, audio)
walker	Walker application launcher (GTK4 service mode for instant startup)

Moonarch Ecosystem

Moonarch is the deployment and configuration layer. Three companion projects provide the Wayland session UI — all built with Rust + gtk4-rs and sharing Catppuccin Mocha theming:

Project	Role	Installed via
moongreet	greetd greeter (GTK4 Layer Shell, fingerprint, i18n)	paru -S moongreet-git
moonlock	Wayland lock screen (ext-session-lock-v1, PAM, fprintd)	paru -S moonlock-git
moonset	Power menu overlay (GTK4 Layer Shell)	paru -S moonset-git

These are built from a custom paru package repository added during post-install.

License

MIT