Skip to content

README.md

Latest commit

 

History

History
220 lines (147 loc) · 17.2 KB

README.md

File metadata and controls

220 lines (147 loc) · 17.2 KB
Raw

Omarchy preferences

Small, readable scripts for rebuilding a familiar Omarchy development laptop after a reinstall or on another machine.

Remote development

Run configure-remote-development.sh to apply these preferences:

Setting Result
Idle screen lock Disabled
Idle screensaver Disabled
Close the lid while plugged in Stay awake and unlocked
Close the lid on battery Keep the existing battery suspend policy and Omarchy lid handler
Manual lock and lock before sleep Keep the existing behavior
Displays when opening or closing the lid Keep Omarchy's monitor handling

These preferences intentionally leave the desktop accessible when unattended. Lock it manually when needed. The AC exception applies when the lid closes; unplugging an already closed laptop is a separate power event.

Install

This targets Omarchy 4's Lua Hyprland configuration and Quickshell idle service. It needs the existing shell.json, bindings.lua, Omarchy lid/monitor commands, Python 3, luac, and a reloadable systemd-logind. It does not target older hyprland.conf/hypridle.conf installations.

From an active terminal in the Omarchy desktop:

git clone https://github.com/lmachineone/bash-scripts.git
cd bash-scripts
bash omarchy/configure-remote-development.sh

If the repository is already checked out, run the last command from its root. Run it as your normal user. Enter the administrator password only at the local sudo prompt.

The script changes only the two idle values, a marked personal lid binding, its helper, and one logind drop-in. It keeps vendor files untouched and reloads Hyprland and logind without rebooting. Existing stay-awake settings are preserved.

Running it again replaces its own marked binding instead of adding another. If another custom lid-close binding exists, it stops before changing live settings; reconcile that binding first. Do not install overlapping lid overrides.

Files and recovery

Installed file Purpose
~/.config/omarchy/shell.json Set idle.screensaver and idle.lock to 0
~/.config/hypr/bindings.lua Route lid close through the AC-aware helper
~/.local/bin/bash-scripts-omarchy-lid-close Skip locking only when logind confirms AC power
/etc/systemd/logind.conf.d/90-omarchy-remote-development.conf Set only HandleLidSwitchExternalPower=ignore

The installer prints a private backup directory under ~/.local/state/bash-scripts/omarchy/. It stores the previous files there, never in this repository. Every run creates its own backup; keep the first one to recover the original settings. A backup of an installed helper or drop-in exists only if that file existed before that run. Files ending in .new are prepared replacements, not originals.

To undo, use the backup from the run you want to reverse. Review later edits before restoring complete files. Usually the narrow recovery is:

  1. Restore just idle.screensaver and idle.lock from the backed-up shell.json.
  2. Remove the BEGIN/END bash-scripts Omarchy AC lid override block from bindings.lua.
  3. Restore the previous helper and drop-in if they were backed up. Otherwise remove only the two installed files listed above.
  4. Run hyprctl reload and sudo systemctl reload systemd-logind.

An existing locked session stays locked until you unlock it. For a new setup, check the lid behavior while physically present before relying on unattended access. Other logind overrides or desktop power settings can affect the result.

VM host prerequisites

install-vm-host-dependencies.sh prepares the packages for a headless KVM/libvirt host on Arch/Omarchy x86_64:

# Read-only check. Exit 2 means packages are missing.
bash omarchy/install-vm-host-dependencies.sh

# Install missing packages, with the normal pacman confirmation.
bash omarchy/install-vm-host-dependencies.sh --install

Add --yes only for an already reviewed unattended transaction. The package set is qemu-base, libvirt, dnsmasq, edk2-ovmf, cloud-image-utils, nftables, curl, gnupg, python, and jq. Pacman also installs their dependencies. Run as your normal user with sudo, or as root through an approved provisioning path.

The installer uses existing package indexes. It never runs pacman -Sy or a general OS upgrade. It stops if the cached indexes show pending upgrades or the transaction cannot resolve. Keep the system current through Omarchy's normal update process before installing; stale indexes can refer to packages that mirrors no longer carry. On a mirror or dependency error, stop and resolve the system update separately rather than attempting a partial upgrade.

No VM, network, user/group membership, firewall policy or libvirt service is configured by this script. Package hooks can still run. Set up the intended network protection and guarded VM startup separately before activating libvirt or guests. The Ubuntu guest installer covers packages inside a dedicated guest.

Reruns skip installation when all prerequisites are present. Inspect /var/log/pacman.log to identify the original package transaction for recovery. Retain packages used by other workloads; do not blanket-remove dependencies. Disabling a later VM is separate from removing these packages.

Docker and NVIDIA containers

install-ai-container-dependencies.sh prepares Docker Compose and GPU containers on Arch/Omarchy x86_64. It uses Arch's official docker, docker-compose, and nvidia-container-toolkit packages. The toolkit brings libnvidia-container as a dependency; no AUR helper or separate CUDA development toolkit is needed for prebuilt inference images.

# Read-only package and host-driver check. Exit 2 means a prerequisite is missing.
bash omarchy/install-ai-container-dependencies.sh

# Install only missing packages, with normal pacman confirmation.
bash omarchy/install-ai-container-dependencies.sh --install

Use --yes only for an already reviewed unattended package transaction. The installer requires a working nvidia-smi and leaves the host GPU driver alone. It uses existing package indexes and stops on pending upgrades. Use Omarchy's normal full update first when indexes are stale or packages no longer resolve; do not run pacman -Sy alone. Package hooks can run during installation. The script does not activate Docker or configure GPU access.

Register the NVIDIA runtime

Do this during an authorized host maintenance window. First inspect systemctl status docker.service and identify existing workloads. Starting Docker can restart existing containers and Dokploy services; restarting a running daemon can interrupt them. Installing packages alone is not permission to interrupt those workloads.

Preserve the existing daemon configuration privately before using NVIDIA's supported merge command. Run this block in one Bash shell on the target host:

sudo install -d -m 0700 /var/lib/bash-scripts/docker-nvidia-backups
backup_dir=$(sudo mktemp -d /var/lib/bash-scripts/docker-nvidia-backups/backup.XXXXXXXX)
if sudo test -e /etc/docker/daemon.json; then
    sudo cp -a /etc/docker/daemon.json "$backup_dir/daemon.json"
else
    sudo touch "$backup_dir/daemon-json-was-absent"
fi
printf 'Private recovery directory: %s\n' "$backup_dir"
sudo nvidia-ctk runtime configure --runtime=docker
sudo dockerd --validate --config-file=/etc/docker/daemon.json

The command updates /etc/docker/daemon.json while retaining other settings. Do not use --set-as-default: ordinary containers should keep their existing runtime. If validation fails, restore the previous configuration before activation. Keep the backup outside this public repository.

After validation, choose the action matching the existing daemon state:

# Docker was stopped: enable boot startup and start it.
sudo systemctl enable --now docker.service

# Docker was already running: apply the runtime change during its maintenance window.
sudo systemctl restart docker.service

Run only the applicable activation command. Do not reinstall Dokploy or initialize another Swarm. Do not add a user to the docker group automatically; use the existing access policy or sudo.

Verify and recover

docker compose version
sudo docker info --format '{{json .Runtimes}}'
# Downloads this sample image if absent, then removes its test container.
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

The runtime list must include nvidia, and the container must see the intended GPU. This sample follows NVIDIA's official workload check; it is an explicit execution step, not part of the installer's default check. Use the application's pinned image for final inference proof. Recheck GPU access after daemon changes; NVIDIA documents a systemd cgroup issue where daemon-reload can revoke access from running GPU containers.

To reverse runtime registration, restore the private daemon.json backup, or remove the newly created file only if it was previously absent and no later settings were added. Validate the resulting configuration and restart Docker in a maintenance window. Preserve the previous service enablement state. Package removal is separate: inspect /var/log/pacman.log and retain packages used by other workloads. Application/model volumes and backups have their own retention policy.

Docker socket ordering with a privacy guard

Apply this only when an existing Docker socket guard waits for normal services, such as Tailscale or network readiness, and systemd reports an ordering cycle through sockets.target and basic.target. The default socket ordering runs before those targets, while the guard needs services that start afterward. Enabled unit flags do not prove that startup succeeds.

docker.socket.d/95-private-boot-order.conf removes the conflicting default early-socket ordering and explicitly retains initialization and shutdown dependencies. It leaves existing privacy requirements, binding dependencies and pre-start checks in place. It does not install a guard or change Docker's service unit, firewall, ports or daemon configuration. Do not apply it as a generic Docker optimization.

First retain a private copy of the current drop-ins and record service/container state. Check whether an equivalent correction already exists; keep one owned drop-in. During a coordinated maintenance slot, install the file without overwriting another owner's configuration:

sudo install -d -m 0755 /etc/systemd/system/docker.socket.d
if sudo test -e /etc/systemd/system/docker.socket.d/95-private-boot-order.conf || \
    sudo test -L /etc/systemd/system/docker.socket.d/95-private-boot-order.conf; then
    printf 'Existing drop-in: inspect it before making changes.\n' >&2
else
    sudo install -m 0644 omarchy/docker.socket.d/95-private-boot-order.conf \
        /etc/systemd/system/docker.socket.d/95-private-boot-order.conf
fi
sudo systemd-analyze verify --recursive-errors=yes --man=no \
    default.target docker.service docker.socket

Include the actual privacy guard and adjacent boot units in verification. Inspect the diagnostics as well as the exit code: a discarded job can break a cycle while leaving a zero exit status. Stop if any ordering cycle or dropped required job remains. After a clean result, run sudo systemctl daemon-reload, then read back DefaultDependencies, Requires, BindsTo, After, Before, Conflicts and ExecStartPre with systemctl show docker.socket. Check the guard, workload identities, private access and health again. A daemon reload should not restart Docker, but NVIDIA's cgroup caveat above still requires a safe workload slot.

For rollback, remove only this newly installed, unchanged drop-in, or restore its exact preimage if an authorized replacement was made. Reload systemd in another coordinated slot. This restores the previous ordering, including the original defect; it is a recovery handle, not a permanent fix.

Configuration verification is separate from reboot acceptance. Before a controlled reboot, establish disk-unlock and local recovery access, quiesce affected work, and capture service/configuration identity. After boot, confirm the guard precedes Docker, no required start job was discarded, the original services return automatically, private access works and forbidden ingress stays denied. Encrypted storage may require someone at the machine before SSH can return.

Sources checked 1 November 2026: Arch Docker, Arch Compose, Arch NVIDIA Container Toolkit, NVIDIA installation and Docker configuration, NVIDIA sample workload, Docker daemon startup, systemd socket dependencies, and systemd unit verification. The Arch Wiki could not be read during this research; these package and vendor sources support the procedure directly.

Predator PH315-53 fan cooling

predator-ph315-53-fans.py selects firmware Auto or Maximum for both fans. It supports only Predator PH315-53 with BIOS V2.04, the verified hardware/firmware pair. It uses the kernel's existing ec_sys module, Python 3 and powerprofilesctl; it installs no packages or service.

# Read fan modes and the firmware's raw speed values.
sudo python3 omarchy/predator-ph315-53-fans.py status

# Select maximum cooling for both fans.
sudo python3 omarchy/predator-ph315-53-fans.py max

# Return both fans to firmware automatic control.
sudo python3 omarchy/predator-ph315-53-fans.py auto

Run from this repository on the laptop. The script changes only the two fan-mode bytes. It preserves the Linux power profile, CoolBoost, voltage settings, CPU/GPU performance controls and Turbo LED. It stops on unknown mode values or a detected conflicting fan controller. The register map comes from the exact-model PredatorNonSense implementation, by Phani Pavan Kambhampati; its other hardware controls are not used.

To keep the command available independently of the checkout, install the reviewed script:

sudo install -m 0755 omarchy/predator-ph315-53-fans.py /usr/local/bin/predator-ph315-53-fans
sudo predator-ph315-53-fans status

Use sudo predator-ph315-53-fans max or sudo predator-ph315-53-fans auto afterward. Removing this installed file does not change the current fan mode; return to auto first when retiring it.

The command verifies mode readback and attempts to restore the original pair if verification fails. It unloads ec_sys only when it loaded that module itself. Firmware keeps the requested fan mode afterward; reboot, suspend or a hardware key may change it. There is no boot-time persistence. Use auto for normal recovery, and do not run another fan utility concurrently.

The displayed speed numbers are raw EC readings, not independently calibrated RPM. Maximum mode and rising readings show a control response; check physical airflow and temperatures separately. This is model-specific low-level hardware control, not a generic fan script. Keep vents clear and the lid open under sustained load.

GitHub access on a replacement machine

Generate a new SSH key on each machine; do not copy a private key into this repository:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_github_omarchy -C "omarchy-github"

Add only the .pub file to your GitHub account's SSH keys. Set the matching identity in your private ~/.ssh/config, preserving any existing GitHub configuration:

Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github_omarchy
    IdentitiesOnly yes

Use your normal passphrase/SSH-agent policy. On the first connection, compare the server fingerprint with GitHub's published fingerprints, then check access with ssh -T git@github.com. GitHub SSH access is separate from gh or Codex authentication.

Keeping this folder useful

Add a small script and document its purpose, requirements, changed files, and recovery steps whenever a new preference is adopted. Work directly on main; no worktrees or pull requests are needed.

Keep this public folder limited to scripts and documentation. Do not add tests, proof reports, logs, personal configuration dumps, private host addresses, credentials, keys, or backups. If a future script needs a secret, obtain it at runtime from a private local source or prompt; never put it in arguments, printed output, or a committed example. Ignore rules are a convenience, not a substitute for reviewing the diff before publishing.