Troubleshooting and Recovery – Installing in Chroot Environments

When installing Omarchy inside a chroot (e.g. via arch-chroot), starting services during install can fail. Omarchy provides a chroot mode to enable services without starting them, deferring actual service activation until first boot.

Index

1. Overview
2. Enabling Chroot Mode
3. chrootable_systemctl_enable Function
4. Affected Installation Scripts
5. Usage Example
6. Common Pitfalls & Tips
7. Recovery Steps

Overview

Omarchy’s chroot mode ensures services are enabled (so they start on boot) but not started during the install process. This avoids failures when systemd daemons cannot run in a chroot.

Enabling Chroot Mode

Set the environment variable OMARCHY_CHROOT_INSTALL=1 before running the installer.

chrootable_systemctl_enable Function

This helper function lives in install/preflight/chroot.sh. It checks OMARCHY_CHROOT_INSTALL and chooses whether to start services immediately.

# install/preflight/chroot.sh

# Starting with OMARCHY_CHROOT_INSTALL=1 puts the installer into chroot mode
chrootable_systemctl_enable() {
  if [ -n "${OMARCHY_CHROOT_INSTALL:-}" ]; then
    sudo systemctl enable "$1"
  else
    sudo systemctl enable --now "$1"
  fi
}

This function is sourced early in install.sh, making it available to all subsequent install and config scripts .

Affected Installation Scripts

Any script that would normally run systemctl enable --now should use the chroot-aware helper. Common examples:

• Printer setup (install/config/hardware/printer.sh):

  • cups.service
  • avahi-daemon.service
  • cups-browsed.service

• Bluetooth (install/config/hardware/bluetooth.sh):

  • bluetooth.service

• Limine Snapper Sync (install/login/limine-snapper.sh):

  • limine-snapper-sync.service

In each, services are enabled for first-boot but not started inside the chroot.

Usage Example

1. Mount and prepare your target filesystem:

   mount /dev/sdXn /mnt
   arch-chroot /mnt /bin/bash
   

2. Enable chroot mode and start Omarchy installer:

   export OMARCHY_CHROOT_INSTALL=1
   git clone https://github.com/magarrent/omarchy.git ~/.local/share/omarchy
   ~/.local/share/omarchy/install.sh
   

3. Verify the variable was recognized:

   source ~/.local/share/omarchy/install/preflight/show-env.sh
   

   You should see OMARCHY_CHROOT_INSTALL=1 in the output .

Common Pitfalls & Tips

• systemctl failures inside chroot: ensure /sys/fs/cgroup, /run, and /var are properly mounted.
• Missing dependencies: services won’t start until actual boot; validate in first-run mode.
• Logs: check /mnt/var/log/pacman.log and mount the journal directory if troubleshooting service enabling.

Recovery Steps

1. Chroot back in after a failed install and re-run the installer with OMARCHY_CHROOT_INSTALL=1.
2. Inspect service unit files in /etc/systemd/system for correctness.
3. After rebooting into the newly installed system, confirm services are enabled and start them manually if needed:

   systemctl start <service>.service
   systemctl status <service>.service
   

4. Use first-run mode (~/.local/state/omarchy/first-run.mode) to perform post-install tweaks.

By following this chroot-aware installation flow, you can reliably set up Omarchy in containerized or chroot environments without service startup errors.