Ansible automation for setting up a freshly installed Omarchy desktop (4.5), with a menu to choose what to apply.
Each automation is split into a system phase (packages, /etc, PAM,
the login screen, signed plugin builds — run by an administrator) and a
user phase (your ~/.config, session services and shell plugins — run
as yourself, in your own session).
It can also set the machine up for several users, opt-in: the
users, omarchy-multiuser and shared-checkout features (all off by
default, so a stock single-owner Omarchy keeps its autologin and its own
tools) create the accounts, replace the Omarchy tools that assumed a single
owner with omarchy-multiuser
— each person's password is their own disk key, and the one typed at the
disk prompt or on the login screen says whose desktop opens — and publish a
copy every user can run their own phase from. See docs/multi-user.md for the model.
Everything this repository can do is listed in features.yml,
the catalog, and documented in docs/features.md
(generated from it): what each feature adds, modifies or removes in a stock
Omarchy, whether it is on by default, and whether turning it off undoes it.
just configure # gum menu: pick apps and features; offers to apply them- Apps, by category (web browsers, password managers, office suites, graphics, PDF viewers, video, notes, editors, terminal workspaces, file managers), each with its installation alternatives — native, AUR, Flathub or a release bundle (e.g. Google Chrome, Firefox native or Flatpak, Brave Origin or Brave Flatpak; ONLYOFFICE, LibreOffice or the ArtCraft suite through its launcher). Several can be installed side by side; where a category has a default app (browser, password manager, PDF viewer, file manager) the menu asks for it. Apps are declarative: one left unchecked is uninstalled, Omarchy's own included (after a confirmation).
- Features, by group: accounts and login, desktop tweaks, Omarchy shell plugins, development tools, Portuguese (Brazil), hardware, and opt-in ones (Secure Boot, Homebrew, the BGRT boot theme, Google Drive, the Yubikey GPG key).
fish is every account's login shell; that isn't a choice. Omarchy's web apps (YouTube, WhatsApp, ...) are kept native or rebuilt with an installed browser — the menu asks, offering Firefox Taskbar Tabs or Chrome/Brave/Chromium PWAs. Taskbar Tabs open tiled fullscreen; PWAs open as ordinary tiled windows.
Your choices are saved in ~/.config/omarchy-setup/features.yml; anything
you never chose takes the catalog's default. Each user runs the menu for
their own user phase; the system phase follows the administrator's.
- An Omarchy 4.5 desktop: the plays rely on its packages and commands.
run0(part of systemd, so already there on Arch) and, for the system phase, a user in thewheelgroup. Other users need not be: their part is the user phase only.- The libfprint playbook builds with
makepkgon the host (no container); it replaces the officiallibfprint/libfprint-gitviapacman -U. - The Secure Boot playbook only covers Limine + limine-entry-tool.
Neither just nor ansible need to be pre-installed: ./bootstrap.sh
installs just; just setup then installs ansible and the
community.general collection on its own.
Privileged tasks escalate with run0
(the community.general.run0 become plugin, set as become_method in
ansible.cfg). run0 authenticates through polkit, and Omarchy's shell
registers a graphical polkit agent, so a bare run0 would pop up an
authentication dialog for every privileged task, and polkit doesn't
retain the authorization between separate run0 processes (checked on this
machine). A playbook run has dozens of privileged tasks.
So every recipe that needs root runs ansible-playbook through
run-empowered.sh, i.e. under run0 --empower: the
playbook keeps running as your user (same $HOME, systemctl --user, ...)
but with all capabilities and the empower group, for which systemd's stock
polkit rule allows every action. You authenticate once, in the polkit
dialog that appears at the start (fingerprint or password, whatever the
dialog offers), and each become: true task's own run0 --user=root inside
passes without another prompt. There is no --ask-become-pass: no password
is handed to run0.
Nothing persists: no polkit rule granting passwordless root is installed, and the privileges live only in that process tree while it runs. Per run0(1), other unprivileged processes of your user have privileges over an empowered process, so don't run a playbook while untrusted software is running in your session.
Careful with hidden/unattended terminals: the dialog needs someone at the
screen. A caller without a human present should pass
ansible_become_flags=--no-ask-password (or use run0 --no-ask-password) to
fail fast instead of waiting.
As an administrator, on your own account:
git clone https://github.com/lbssousa/omarchy-setup.git
cd omarchy-setup
./bootstrap.sh # installs `just`, if missing — only needs to run once
just setup # the menu the first time, then the system phase and your user phaseLater runs:
just configure # change your choices (and apply them)
just setup # system phase, then your user phase
just system | just user # one phase only
just apply capslock nix # only these features now (even if switched off)
just apply apps # only the appsPersonal data stays out of the repository: your git identity, the Google
account for rclone and (administrator) the accounts' full names go in
~/.config/omarchy-setup/local.yml (template:
users/local.example.yml).
Adding someone (turn on the multi-user features first, in just configure: users, omarchy-multiuser, shared-checkout): declare them
in group_vars/all/users.yml (their full name in your local.yml; their
settings, if any, in users/<name>.yml), commit, then:
just users # creates the account and asks for its password, also its disk key
just publish # world-readable copy in /opt/omarchy-setup + omarchy-setup-userThey log in from the greeter (Omarchy's first-run setup runs as for the owner) and apply their part, from a terminal in their session:
omarchy-setup-user # same as `just user`, from the shared copyjust check syntax-checks everything, the boundary between the phases, the
catalog against the plays' tags and that docs/features.md is current
(just docs regenerates it). The playbooks are idempotent — rerunning is
safe.
Not Ansible, run on their own: just typesetting (TeX Live, LilyPond and
Gregorio on the host — see local-typesetting/README.md), just ssh-yubikey
/ just ssh-yubikey-disable (the Yubikey's resident SSH keys, prompts for
the FIDO2 PIN) and
just efi-cleanup / just efi-cleanup-apply (list, then remove, UEFI boot
entries left over from earlier installs). Secure
Boot has a walkthrough: docs/secureboot.md.
| File/Directory | Role |
|---|---|
features.yml |
The catalog: features and apps, defaults, what each does |
docs/features.md |
The catalog as a document (just docs) |
scripts/configure.sh |
The gum menu (just configure) |
scripts/features.py |
Resolves the catalog with your choices; checks it (just check); generates the docs |
scripts/run-phase.sh |
Runs a phase: system only for wheel, under run-empowered.sh; user only as the user; passes users/$USER.yml, local.yml, the resolved selection and its tags |
scripts/check-phases.sh |
Fails when a user-phase play becomes root or installs packages, or a system-phase play talks to a user session |
bootstrap.sh |
Installs just, if missing |
run-empowered.sh |
Runs ansible-playbook under run0 --empower (see Privilege above) |
site.yml, system.yml, user.yml |
Both phases; the system phase's plays; the user phase's plays. Each play is tagged with its feature id (apps for the app plays) |
playbooks/system/, playbooks/user/ |
One file per feature (or a few closely related ones), in its phase |
playbooks/{system,user}/apps/ |
The app categories: packages installed or removed as chosen, then each category's extras (default apps, Firefox defaults, PWA policy, web apps, password manager keybind/autostart/SSH agent, Zathura, svg2tikz, Emacs, Zed) |
playbooks/tasks/ |
Shared tasks: app install/removal (app-package.yml, aur-build.yml, artcraft-launcher.yml), Hyprland blocks (hypr-user-block.yml), Flatpak overrides, signed-tag checkouts, web apps, handlers |
playbooks/files/, playbooks/templates/ |
Static files and Jinja2 templates |
group_vars/all/main.yml |
Variables for every automation (machine defaults) |
group_vars/all/users.yml |
The machine's accounts (omarchy_users); full names live in the untracked local.yml |
group_vars/all/target.yml |
target_user/target_home: the account a run configures |
users/<name>.yml |
Each user's own settings (see users/README.md), e.g. their web apps |
docs/ |
The feature catalog, the multi-user model, the Secure Boot walkthrough |
local-typesetting/ |
TeX Live + LilyPond + Gregorio on the host (just typesetting) |
requirements.yml |
Required Ansible collections |
Justfile |
just configure, setup, system, user, apply, check, ... |