moonarch/README.md

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-persistent	kanshi auto-switches output profiles on hotplug. wdisplays-persistent saves changes directly to kanshi config.
Notifications	swaync	GTK4 notification daemon with DND toggle, grouping, MPRIS support. Fractional scaling via native GTK4.
Clipboard	cliphist + Walker	Clipboard history stored in runtime dir, wiped on session start. Walker provides the picker UI.
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).
Night Light	wlsunset	Wayland-native blue light filter via wlr-gamma-control. Toggleable from Waybar brightness group.
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 ~95 packages, all configs, themes, services, and user setup.

Update

moonup   # or: moonarch-update

Interactive updater that upgrades system and AUR packages, reconciles package lists against what's installed, and cleans orphaned packages. Config deployment happens automatically via the moonarch-git package on paru -Syu.

Health Check

moondoc   # or: moonarch-doctor

Diagnostic tool that verifies the system state against moonarch defaults: services, configs, packages, helper scripts, firewall, shell and directory permissions. Reports pass/fail/warn per check with a summary at the end.

Project Structure

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

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

scripts/
  lib.sh                        Shared helpers sourced by post-install.sh
  post-install.sh               Main automation (packages, configs, themes, services)
  moonarch-update               Interactive updater (deployed to /usr/bin/ as moonup)
  moonarch-doctor               System health checker (deployed to /usr/bin/ as moondoc)

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 + moonarch theme (Catppuccin Mocha)
    foot/foot.ini                 Terminal: font, colors, keybinds
    swaync/config.json, style.css Notifications: appearance, behavior, MPRIS
    kanshi/config                 Display profiles (empty seed, user-configured via wdisplays)
    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/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-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
    moonarch-waybar-batsaver      Waybar module: battery conservation mode indicator
    moonarch-waybar-updates       Waybar module: package update checker (repo + AUR)
    moonarch-batsaver-toggle      Toggle battery charge limit (80% ↔ 100%)
    moonarch-nightlight           Toggle wlsunset blue light filter on/off
    moonarch-waybar-nightlight    Waybar module: nightlight status

  shell/zshrc                   Zsh config: prompt, aliases, FZF, completion
  etc/greetd/                   greetd daemon + greeter Niri config
  etc/moongreet/                moongreet configuration
  etc/systemd/user/             Systemd user services (cliphist, kanshi, walker, nautilus)
  etc/systemd/system/           System service (battery conservation restore on boot)
  etc/udev/rules.d/             udev rules (battery threshold permissions)
  backgrounds/wallpaper.jpg     Default wallpaper (shared by desktop, greeter, lock screen)

Startup Sequence

greetd ─► niri (greeter instance) ─► moongreet ─► user authenticates
                                                         │
                                                         ▼
                                                   niri (user session)
                                                         │
                           ┌──────────┬────────┬────────┬──────────┐
                           ▼          ▼        ▼        ▼          ▼
                        waybar     swaync   foot     waypaper   nm-applet  wlsunset
                        (bar)    (notify) (server)  (wallpaper)  (VPN)    (nightlight)

                        systemd user services (graphical-session.target):
                        kanshi, cliphist, walker, nautilus

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
Mod+Escape	Session menu (moonset)
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 (includes system config)
Waybar	/etc/xdg/waybar/	~/.config/waybar/
Walker	/etc/xdg/walker/	~/.config/walker/
Foot	/etc/xdg/foot/foot.ini	~/.config/foot/foot.ini
swaync	/etc/xdg/swaync/	~/.config/swaync/
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/bin/moonarch-* are not meant to be overridden — they are part of the system and updated via paru -Syu.

System Services

Service	Purpose
greetd	Login greeter (runs moongreet inside Niri)
NetworkManager	Network management (WiFi, VPN, Ethernet)
bluetooth	Bluetooth stack (bluez)
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
cliphist	Clipboard history (wipes on session start, stores in runtime dir)
kanshi	Dynamic display configuration (auto-switch output profiles on hotplug)
nautilus	File manager preload (faster first launch)
stasis	Idle manager (dimming, DPMS, lock, suspend on AC/battery plans)
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