Turning My Linux Desktop into Infrastructure as Code

#

At some point, dotfiles stop being enough.

Managing my Hyprland config, Waybar setup, kitty theme, shell aliases, wallpaper-driven colors, and application preferences with chezmoi gets me a long way. It means my environment feels familiar across machines. It means my config is versioned. It means I can roll back bad ideas instead of trying to remember what file I edited at 1 AM.

But dotfiles only solve one layer of the problem.

They do not install the packages those configs depend on. They do not enable the services my desktop expects to be running. They do not decide whether this machine needs NVIDIA-specific packages, laptop power management, Bluetooth, Docker, development tooling, screenshot utilities, clipboard helpers, or the right AUR packages.

That is where the rebuild story starts to get messy.

My goal for this part of the series is simple:

I want to be able to take a fresh Arch machine and turn it into my working Linux desktop in roughly 15 minutes.

Not because I reinstall constantly. Not because shaving a few minutes off setup time is life-changing. The real value is confidence.

If my laptop dies, I can rebuild. If my desktop gets weird, I can start clean. If I buy a new machine, I am not spending an entire weekend remembering every package, service, and tweak I rely on.

This post is about expanding my dotfiles into something closer to Infrastructure as Code for my workstation.

The Problem: Dotfiles Are Not the Whole System

#

In the previous parts of this series, I focused heavily on reproducibility:

• Hyprland config structure
• modular config files
• chezmoi for dotfile management
• wallpaper-driven theming
• keeping multiple machines in sync
• avoiding a bloated desktop setup

That solved the “how do I keep my config clean?” problem.

But a Linux desktop is more than config files.

My Hyprland setup depends on a collection of packages and services. Some are obvious. Some are easy to forget until they are missing.

For example, a Wayland desktop might need tools for:

• display management
• authentication agents
• screenshots
• screen recording
• clipboard history
• notifications
• portals
• PipeWire audio
• Bluetooth
• fonts
• themes
• terminal tools
• development tools
• Docker
• browsers
• editor tooling
• AUR packages
• hardware-specific drivers

The problem is not installing these one time. The problem is remembering the full shape of the system six months later.

That is where I want my setup to become more intentional.

I do not want my desktop to be a pile of manually installed packages and undocumented assumptions. I want it to look more like the infrastructure I manage professionally:

• declarative where practical
• version-controlled
• repeatable
• split by concern
• safe to run more than once
• aware of machine-specific differences

In other words, I want my workstation to be treated like infrastructure.

The Goal: A New Machine in 15 Minutes

#

The target state is not a fully automated bare-metal Arch installer.

At least not yet.

For now, I am assuming a base Arch install already exists with:

• networking working
• a user account created
• sudo configured
• Git installed
• internet access available
• disk partitioning already handled
• the system booted and usable from a TTY or minimal environment

That is a practical starting point.

From there, I want to clone my dotfiles repository, run one bootstrap command, and let the machine converge into my preferred environment.

Something like this:

1
2
3

git clone git@github.com:dcajio/dotfiles.git ~/.local/share/chezmoi
cd ~/.local/share/chezmoi
./bootstrap.sh

The bootstrap process should handle:

1. Installing required pacman packages
2. Installing yay if it is not already present
3. Installing AUR packages
4. Applying my chezmoi dotfiles
5. Enabling system services
6. Enabling user services
7. Handling machine-specific differences
8. Leaving me with a usable Hyprland workstation

That is the vision.

The important part is that this script should be safe to rerun. A rebuild script that only works once is not automation. It is a fragile install recipe.

Repository Structure

#

Before writing the script, I want a clean structure.

I already use chezmoi, so the dotfiles repository is the obvious home for this. But I do not want one giant script filled with every package, service, and conditional branch.

I want the repo to be readable.

A structure like this makes sense:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

~/.local/share/chezmoi/
├── bootstrap.sh
├── packages/
│   ├── pacman-core.txt
│   ├── pacman-desktop.txt
│   ├── pacman-dev.txt
│   ├── pacman-hyprland.txt
│   ├── pacman-laptop.txt
│   ├── aur-core.txt
│   ├── aur-desktop.txt
│   └── aur-dev.txt
├── services/
│   ├── system.txt
│   └── user.txt
├── scripts/
│   ├── install-yay.sh
│   ├── install-pacman-packages.sh
│   ├── install-aur-packages.sh
│   ├── enable-system-services.sh
│   ├── enable-user-services.sh
│   └── detect-machine.sh
└── home/
    └── dot_config/
        └── ...

This keeps the system split into logical pieces:

• package lists live in packages/
• service lists live in services/
• reusable scripts live in scripts/
• chezmoi still owns the actual home directory config

This is the same principle I use when organizing infrastructure or application code: separate intent from implementation.

The package files describe what I want installed. The scripts describe how to install them. The dotfiles describe how I want the environment configured.

Package Bootstrapping with pacman

#

The first layer is official Arch packages.

I want these package lists to be boring text files. One package per line. Comments allowed. Blank lines ignored.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# packages/pacman-core.txt

base-devel
git
curl
wget
unzip
rsync
jq
fzf
ripgrep
fd
bat
eza
zoxide
man-db
man-pages

Then a desktop-specific list:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# packages/pacman-desktop.txt

hyprland
waybar
kitty
wofi
dunst
swww
grim
slurp
wl-clipboard
xdg-desktop-portal
xdg-desktop-portal-hyprland
pipewire
pipewire-pulse
wireplumber
pavucontrol
networkmanager
blueman
brightnessctl
playerctl
polkit-gnome
noto-fonts
noto-fonts-emoji
ttf-jetbrains-mono-nerd

And a development list:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# packages/pacman-dev.txt

docker
docker-compose
nodejs
npm
python
python-pip
go
rust
neovim
github-cli
openssh

The install script can read all of these files and pass the packages into pacman.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

install_pacman_file() {
  local file="$1"

  if [[ ! -f "$file" ]]; then
    echo "Package file not found: $file"
    return 0
  fi

  mapfile -t packages < <(
    grep -vE '^\s*#' "$file" |
    grep -vE '^\s*$'
  )

  if [[ "${#packages[@]}" -eq 0 ]]; then
    echo "No packages found in $file"
    return 0
  fi

  echo "Installing pacman packages from $file"
  sudo pacman -S --needed --noconfirm "${packages[@]}"
}

install_pacman_file "$ROOT_DIR/packages/pacman-core.txt"
install_pacman_file "$ROOT_DIR/packages/pacman-desktop.txt"
install_pacman_file "$ROOT_DIR/packages/pacman-dev.txt"

The key flag here is:

1

--needed

That makes the script rerunnable. If a package is already installed, pacman does not reinstall it unnecessarily.

This is one of the most important habits in workstation automation: make every step idempotent where possible.

AUR Bootstrapping with yay

#

I use yay for AUR packages.

That means the bootstrap process needs to account for two cases:

1. yay is already installed
2. yay is missing and needs to be built

I do not want to assume the machine already has everything.

Here is a simple install-yay.sh:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#!/usr/bin/env bash
set -euo pipefail

if command -v yay >/dev/null 2>&1; then
  echo "yay is already installed"
  exit 0
fi

echo "Installing yay"

sudo pacman -S --needed --noconfirm git base-devel

tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT

git clone https://aur.archlinux.org/yay.git "$tmpdir/yay"
cd "$tmpdir/yay"

makepkg -si --noconfirm

Then I can manage AUR packages the same way as official packages:

1
2
3
4

# packages/aur-core.txt

visual-studio-code-bin
google-chrome

Hyprland and desktop niceties may also end up here depending on what I choose to install from the AUR:

1
2
3
4

# packages/aur-desktop.txt

wlogout
hyprpicker

And the AUR install script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

install_aur_file() {
  local file="$1"

  if [[ ! -f "$file" ]]; then
    echo "AUR package file not found: $file"
    return 0
  fi

  mapfile -t packages < <(
    grep -vE '^\s*#' "$file" |
    grep -vE '^\s*$'
  )

  if [[ "${#packages[@]}" -eq 0 ]]; then
    echo "No AUR packages found in $file"
    return 0
  fi

  echo "Installing AUR packages from $file"
  yay -S --needed --noconfirm "${packages[@]}"
}

install_aur_file "$ROOT_DIR/packages/aur-core.txt"
install_aur_file "$ROOT_DIR/packages/aur-desktop.txt"
install_aur_file "$ROOT_DIR/packages/aur-dev.txt"

This gives me a clean split:

• pacman for official repo packages
• yay for AUR packages
• text files for package intent
• scripts for installation behavior

It is simple, but that is the point.

The Main Bootstrap Script

#

The top-level bootstrap.sh should be boring and readable.

I want to be able to open it a year from now and immediately understand the provisioning flow.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

echo "Starting workstation bootstrap"

echo "Updating system packages"
sudo pacman -Syu --noconfirm

echo "Installing pacman packages"
"$ROOT_DIR/scripts/install-pacman-packages.sh"

echo "Ensuring yay is installed"
"$ROOT_DIR/scripts/install-yay.sh"

echo "Installing AUR packages"
"$ROOT_DIR/scripts/install-aur-packages.sh"

echo "Applying chezmoi dotfiles"
chezmoi apply

echo "Enabling system services"
"$ROOT_DIR/scripts/enable-system-services.sh"

echo "Enabling user services"
"$ROOT_DIR/scripts/enable-user-services.sh"

echo "Bootstrap complete"
echo "Reboot recommended"

This is intentionally plain.

The orchestration script should not contain every detail. It should describe the order of operations.

The scripts underneath it can handle the details.

System Services

#

Packages are only part of the workstation. The next layer is services.

On a typical Arch desktop, there are system-level services I expect to be available.

Examples:

1
2
3
4
5

# services/system.txt

NetworkManager.service
bluetooth.service
docker.service

Then the enable script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
SERVICE_FILE="$ROOT_DIR/services/system.txt"

if [[ ! -f "$SERVICE_FILE" ]]; then
  echo "No system service file found"
  exit 0
fi

while read -r service; do
  [[ -z "$service" || "$service" =~ ^# ]] && continue

  echo "Enabling system service: $service"
  sudo systemctl enable --now "$service"
done < "$SERVICE_FILE"

This gives me a simple place to add or remove system services without editing shell logic.

If I decide Docker should not run on a certain machine, I can handle that later through host-specific package and service lists.

User Services

#

User services are just as important on a Wayland desktop.

This could include things like:

• user-level sync tools
• notification helpers
• theme watchers
• wallpaper daemons
• custom scripts
• systemd --user timers
• anything that should run as my user instead of root

A user service list may look like this:

1
2
3
4
5

# services/user.txt

pipewire.service
pipewire-pulse.service
wireplumber.service

And the script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
SERVICE_FILE="$ROOT_DIR/services/user.txt"

if [[ ! -f "$SERVICE_FILE" ]]; then
  echo "No user service file found"
  exit 0
fi

systemctl --user daemon-reload

while read -r service; do
  [[ -z "$service" || "$service" =~ ^# ]] && continue

  echo "Enabling user service: $service"
  systemctl --user enable --now "$service"
done < "$SERVICE_FILE"

One gotcha here is that user services require a working user session. Depending on where the bootstrap script is run from, some user-level services may not behave exactly the same from a TTY as they do inside a graphical session.

That is why this process needs to be practical, not overly magical. I am fine with the script getting the machine 95% of the way there and telling me when a reboot or login cycle is required.

Applying chezmoi

#

Once the required packages exist, chezmoi can safely apply my dotfiles.

This order matters.

If my dotfiles reference binaries that are not installed yet, I do not want the first run to be noisy or broken. So the flow should be:

1. install packages
2. install AUR packages
3. apply dotfiles
4. enable services
5. reboot or log out/in

The chezmoi step itself is simple:

1

chezmoi apply

But this is where the workstation starts to feel like mine again.

This brings back:

• Hyprland config
• Waybar config
• kitty config
• shell config
• Git config
• theme files
• scripts
• application preferences
• machine templates

The dotfiles are still the core of the setup. The bootstrap script just makes sure the machine is ready for them.

Handling Machine-Specific Differences

#

This is where things get interesting.

My desktop and laptop are not identical. Different machines may need different packages, services, and config values.

The obvious examples are:

• NVIDIA vs AMD graphics
• desktop monitor layout vs laptop display
• work machine vs personal machine
• laptop battery tools
• Bluetooth requirements
• hostnames
• input devices
• docking station behavior
• machine-specific Hyprland monitor rules
• secrets and SSH keys
• work-only packages

This is exactly where chezmoi templates start to make sense.

I do not want to maintain completely separate dotfile repos for every machine. That defeats the purpose. I want one repo with conditional behavior.

A simple first step is to have chezmoi prompt for machine type during initialization.

For example, a .chezmoi.toml.tmpl:

1
2
3

[data]
machine_type = "{{ promptStringOnce . "machine_type" "Machine type? desktop/laptop/work" }}"
gpu = "{{ promptStringOnce . "gpu" "GPU type? amd/nvidia/intel" }}"

Then inside a Hyprland template, I can branch:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{{- if eq .gpu "nvidia" }}
# NVIDIA-specific environment variables
env = LIBVA_DRIVER_NAME,nvidia
env = __GLX_VENDOR_LIBRARY_NAME,nvidia
env = NVD_BACKEND,direct
{{- end }}

{{- if eq .machine_type "laptop" }}
# Laptop display
monitor = eDP-1,preferred,auto,1
{{- else }}
# Desktop monitors
monitor = DP-1,2560x1440@144,0x0,1
monitor = DP-2,2560x1440@144,2560x0,1
{{- end }}

That is the kind of difference I want chezmoi to own.

For package and service differences, I can add machine-specific package lists.

1
2
3
4
5
6
7

packages/
├── pacman-core.txt
├── pacman-desktop.txt
├── pacman-dev.txt
├── pacman-laptop.txt
├── pacman-nvidia.txt
└── pacman-work.txt

Then the bootstrap script can decide what to install based on detected or configured machine data.

A simple version could read the hostname:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

hostname="$(hostnamectl --static)"

case "$hostname" in
  daves-desktop)
    MACHINE_TYPE="desktop"
    GPU_TYPE="amd"
    ;;
  daves-laptop)
    MACHINE_TYPE="laptop"
    GPU_TYPE="nvidia"
    ;;
  *)
    MACHINE_TYPE="generic"
    GPU_TYPE="unknown"
    ;;
esac

echo "Machine type: $MACHINE_TYPE"
echo "GPU type: $GPU_TYPE"

That is not perfect, but it is easy to understand.

Long-term, I may prefer chezmoi data for this instead of duplicating machine metadata in Bash. The important part is keeping the machine-specific logic explicit. I do not want hidden assumptions.

Example Machine Detection Script

#

Here is a starting point:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#!/usr/bin/env bash
set -euo pipefail

hostname="$(hostnamectl --static)"

gpu_type="unknown"

if lspci | grep -qi nvidia; then
  gpu_type="nvidia"
elif lspci | grep -qi amd; then
  gpu_type="amd"
elif lspci | grep -qi intel; then
  gpu_type="intel"
fi

machine_type="generic"

if [[ -d /sys/class/power_supply/BAT0 || -d /sys/class/power_supply/BAT1 ]]; then
  machine_type="laptop"
else
  machine_type="desktop"
fi

cat <<EOF
HOSTNAME=$hostname
GPU_TYPE=$gpu_type
MACHINE_TYPE=$machine_type
EOF

That script could be sourced by the bootstrap process:

1
2
3
4
5

eval "$("$ROOT_DIR/scripts/detect-machine.sh")"

echo "Detected hostname: $HOSTNAME"
echo "Detected GPU: $GPU_TYPE"
echo "Detected machine type: $MACHINE_TYPE"

Then I can conditionally install packages:

1
2
3
4
5
6
7

if [[ "$MACHINE_TYPE" == "laptop" ]]; then
  install_pacman_file "$ROOT_DIR/packages/pacman-laptop.txt"
fi

if [[ "$GPU_TYPE" == "nvidia" ]]; then
  install_pacman_file "$ROOT_DIR/packages/pacman-nvidia.txt"
fi

A laptop package file may include:

1
2
3
4
5

# packages/pacman-laptop.txt

tlp
upower
acpi

An NVIDIA file may include:

1
2
3
4
5

# packages/pacman-nvidia.txt

nvidia
nvidia-utils
nvidia-settings

I would rather start simple and improve this over time than try to build the perfect abstraction on day one.

Secrets Do Not Belong in Dotfiles

#

One thing I am not trying to do is store secrets directly in this repo.

SSH keys, API tokens, work credentials, private environment files, and anything sensitive need a separate strategy.

For now, the bootstrap process can create the expected directories and leave reminders.

1
2
3
4

mkdir -p "$HOME/.ssh"
chmod 700 "$HOME/.ssh"

echo "Remember to restore SSH keys separately."

That is not fully automated, but it is safe.

Eventually, this could integrate with a proper secret manager. But I would rather have one manual step than accidentally commit something sensitive into a dotfiles repo.

This is one of those places where infrastructure discipline matters. Reproducibility is good. Accidentally syncing secrets everywhere is not.

Making It Safe to Rerun

#

This is probably the most important part of the whole setup.

A good bootstrap script should not be a one-time install bomb. It should be safe to run again after I edit a package list, add a new service, or change part of the environment.

That means:

• use pacman -S --needed
• use yay -S --needed
• avoid destructive commands
• do not overwrite secrets
• do not blindly delete files
• keep package lists additive
• make service enablement repeatable
• let chezmoi handle dotfile diffs
• print what the script is doing

The script should be boring.

Boring automation is good automation.

The First Full Bootstrap Draft

#

Putting the pieces together, here is what an early version of the main script could look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

log() {
  echo
  echo "==> $1"
}

log "Starting workstation bootstrap"

log "Detecting machine"
eval "$("$ROOT_DIR/scripts/detect-machine.sh")"

echo "Hostname: $HOSTNAME"
echo "Machine type: $MACHINE_TYPE"
echo "GPU type: $GPU_TYPE"

log "Updating system"
sudo pacman -Syu --noconfirm

log "Installing base pacman packages"
"$ROOT_DIR/scripts/install-pacman-packages.sh"

if [[ "$MACHINE_TYPE" == "laptop" && -f "$ROOT_DIR/packages/pacman-laptop.txt" ]]; then
  log "Installing laptop-specific packages"
  "$ROOT_DIR/scripts/install-pacman-file.sh" "$ROOT_DIR/packages/pacman-laptop.txt"
fi

if [[ "$GPU_TYPE" == "nvidia" && -f "$ROOT_DIR/packages/pacman-nvidia.txt" ]]; then
  log "Installing NVIDIA-specific packages"
  "$ROOT_DIR/scripts/install-pacman-file.sh" "$ROOT_DIR/packages/pacman-nvidia.txt"
fi

log "Ensuring yay is installed"
"$ROOT_DIR/scripts/install-yay.sh"

log "Installing AUR packages"
"$ROOT_DIR/scripts/install-aur-packages.sh"

log "Applying chezmoi dotfiles"
chezmoi apply

log "Enabling system services"
"$ROOT_DIR/scripts/enable-system-services.sh"

log "Enabling user services"
"$ROOT_DIR/scripts/enable-user-services.sh"

log "Creating expected local directories"
mkdir -p "$HOME/.ssh"
chmod 700 "$HOME/.ssh"

log "Bootstrap complete"
echo "A reboot or logout/login is recommended before judging the final desktop state."

This is not the final form forever. That is fine.

The point is to establish the pattern:

• define packages in files
• define services in files
• keep scripts small
• detect machine differences
• apply dotfiles after dependencies exist
• make the system rebuildable

Gotchas and Edge Cases

#

This kind of setup sounds clean, but there are always rough edges.

AUR Packages Can Break

#

AUR packages are not the same as official repo packages. Builds can fail. Maintainers can change things. Dependencies can shift.

That is why I do not want the entire system to depend on a fragile chain of AUR packages. Anything critical should come from the official repos when possible.

User Services May Need a Real Session

#

Some systemd --user services behave differently depending on whether I run the script from a TTY, SSH session, or inside the actual graphical environment.

For first bootstrapping, I am okay with enabling what I can and rebooting.

NVIDIA Is Always Its Own Chapter

#

NVIDIA on Wayland can still be weird depending on driver versions, kernel, display manager, and Hyprland behavior.

I do not want NVIDIA-specific environment variables sprinkled randomly through my config. They should be isolated behind templates or dedicated config sections.

Monitor Names Are Not Universal

#

Hyprland monitor configs can break when display names change.

A desktop with multiple monitors needs different rules than a laptop. A docked laptop may need another set entirely.

This is a perfect use case for chezmoi templates or imported host-specific Hyprland config files.

Some Things Should Stay Manual

#

Not everything needs to be automated immediately.

Examples:

• restoring SSH private keys
• logging into browsers
• authenticating password managers
• enrolling work accounts
• pairing Bluetooth devices
• setting up proprietary applications

The goal is not zero manual steps. The goal is eliminating the dumb, repetitive, error-prone setup work.

Final Thoughts

#

This is the point where my Linux desktop starts becoming more than a custom setup.

It becomes a system.

The dotfiles are still important, but they are only one part of the rebuild story. The real win is being able to describe the entire workstation in code:

• what packages it needs
• what services should run
• what configs should apply
• what differs between machines
• what should stay manual
• what can be safely repeated

That is the same mindset I use when working with cloud infrastructure.

A server should not be a mystery. A deployment should not depend on tribal knowledge. A workstation should not either.

My end goal is a Linux desktop that I can rebuild quickly, understand completely, and carry across machines without dragging years of accidental cruft along with it.

That is what “new machine in 15 minutes” really means.

Not perfection.

Confidence.