How the Installer Works: Preflight Checks & Environment Prep

This section walks through Omarchy’s preflight phase, covering environment inspection, error handling, system guards, chroot-aware service enabling, Pacman configuration, migration marking, and first-run mode setup.

Index

Overview
Preflight Flowchart
Script Breakdown
3.1 show-env.sh
3.2 trap-errors.sh
3.3 guard.sh
3.4 chroot.sh
3.5 pacman.sh
3.6 migrations.sh
3.7 first-run-mode.sh
Dependencies & Relationships

Overview

The preflight phase prepares the system before any package installs. It:

Exposes key environment variables.
Sets up error trapping with retry UI.
Enforces system guards (OS, user, CPU, desktop state).
Enables services safely in or out of chroot.
Configures Pacman and refreshes repositories.
Marks available migrations to skip completed ones.
Activates a first-run mode for post-install tasks.

All scripts are sourced in install.sh .

Preflight Flowchart

flowchart TD
  A[Start Installer] --> B[Load Preflight Scripts]
  B --> C[Show Environment Variables]
  C --> D[Trap Errors Setup]
  D --> E[Guard System Checks]
  E --> F[Configure Chroot Services]
  F --> G[Configure Pacman]
  G --> H[Mark Migrations]
  H --> I[Enable First-Run Mode]
  I --> J[Proceed to Packaging]

Script Breakdown

show-env.sh

Displays installation environment variables for debugging.

#!/bin/bash
echo "Installation ENV:"
env | grep -E "^(OMARCHY_CHROOT_INSTALL|OMARCHY_USER_NAME|OMARCHY_USER_EMAIL|USER|HOME|OMARCHY_REPO|OMARCHY_REF)="

Prints variables prefixed with OMARCHY_.
Helps confirm correct invocation context.

trap-errors.sh

Catches failures and offers a retry prompt via gum.

#!/bin/bash
catch_errors() {
  echo -e "\n\e[31mOmarchy installation failed!\e[0m"
  echo "This command halted with exit code $?:" 
  echo "$BASH_COMMAND"
  echo
  gum confirm "Retry installation?" && bash ~/.local/share/omarchy/install.sh || exit 1
}
trap catch_errors ERR

Prints error, exit code, and failed command.
Displays a QR code link to support.
Prompts user to retry the installer.

guard.sh

Ensures the host system meets Omarchy’s prerequisites.

#!/bin/bash
abort() {
  echo -e "\e[31mOmarchy install requires: $1\e[0m"
  gum confirm "Proceed anyway?" || exit 1
}
[[ -f /etc/arch-release ]] || abort "Vanilla Arch"
for marker in /etc/cachyos-release /etc/eos-release /etc/garuda-release /etc/manjaro-release; do
  [[ -f "$marker" ]] && abort "Vanilla Arch"
done
[ "$EUID" -eq 0 ] && abort "Running as root"
[ "$(uname -m)" != "x86_64" ] && abort "x86_64 CPU"
pacman -Qe gnome-shell &>/dev/null && abort "Fresh + Vanilla Arch"
pacman -Qe plasma-desktop &>/dev/null && abort "Fresh + Vanilla Arch"
echo "Guards: OK"

Verifies Vanilla Arch, non-root user, x86_64 CPU.
Checks no existing GNOME/KDE installs.
Aborts or prompts override.

chroot.sh

Enables systemd services in chroot-safe manner.

chrootable_systemctl_enable() {
  if [ -n "${OMARCHY_CHROOT_INSTALL:-}" ]; then
    sudo systemctl enable $1
  else
    sudo systemctl enable --now $1
  fi
}

Uses OMARCHY_CHROOT_INSTALL to toggle --now.
Ensures services start immediately when not in chroot.

pacman.sh

Installs build tools and configures Pacman defaults.

#!/bin/bash
sudo pacman -S --needed --noconfirm base-devel
sudo cp -f ~/.local/share/omarchy/default/pacman/pacman.conf /etc/pacman.conf
sudo cp -f ~/.local/share/omarchy/default/pacman/mirrorlist /etc/pacman.d/mirrorlist
sudo pacman -Syu --noconfirm

Installs base-devel.
Replaces /etc/pacman.conf and mirrorlist with Omarchy defaults.
Refreshes all repos.

migrations.sh

Initializes migration markers to avoid re-running scripts.

#!/bin/bash
OMARCHY_MIGRATIONS_STATE_PATH=~/.local/state/omarchy/migrations
mkdir -p $OMARCHY_MIGRATIONS_STATE_PATH
for file in ~/.local/share/omarchy/migrations/*.sh; do
  touch "$OMARCHY_MIGRATIONS_STATE_PATH/$(basename "$file")"
done

Creates state directory.
Touches a marker for each migration script.
Ensures idempotent migrations.

first-run-mode.sh

Marks system for post-install tasks and grants limited sudo.

#!/bin/bash
mkdir -p ~/.local/state/omarchy
touch ~/.local/state/omarchy/first-run.mode

sudo tee /etc/sudoers.d/first-run >/dev/null <<EOF
Cmnd_Alias FIRST_RUN_CLEANUP = /bin/rm -f /etc/sudoers.d/first-run
$USER ALL=(ALL) NOPASSWD: /usr/bin/ufw
$USER ALL=(ALL) NOPASSWD: /usr/bin/ufw-docker
$USER ALL=(ALL) NOPASSWD: FIRST_RUN_CLEANUP
EOF
sudo chmod 440 /etc/sudoers.d/first-run

Creates a first-run marker file.
Grants passwordless sudo for cleanup and firewall commands.
Prepares post-reboot tasks.

Dependencies & Relationships

install.sh sources all preflight scripts in order .
Default configs live under ~/.local/share/omarchy/default/pacman/.
Migration scripts exist in ~/.local/share/omarchy/migrations/.
First-run state drives later tasks in post-install.
gum and walker provide UI prompts across scripts.

This comprehensive preflight ensures that Omarchy proceeds only on a clean, compatible Arch environment with robust error recovery and smooth service setup.

Search this space