# archsetup

Automated Arch Linux installation, dotfile management, and machine maintenance for a personal workstation, driven by a single Bash script, GNU Stow, and a handful of helper utilities.

[Overview](#overview) | [Features](#features) | [Requirements](#requirements) | [Installation](#installation) | [Configuration](#configuration) | [Dotfile Management](#dotfile-management) | [Desktop Environments](#desktop-environments) | [Testing](#testing) | [Contributing](#contributing) | [License](#license)

> **Note:** This is one person's personal Arch setup. It works as-is on that machine; if you fork it, change the hardcoded repositories and account details first (see [Configuration](#configuration)).

## Overview

archsetup turns a freshly installed Arch Linux box into a working desktop. It does three things:

1. **Provisions the system.** The `archsetup` script installs packages, creates the primary user, builds suckless tools and an Emacs config from source, enables systemd services, sets up an AUR helper, configures the firewall, and installs a desktop environment (DWM on Xorg, or Hyprland on Wayland).
2. **Manages dotfiles.** Configuration lives under `dotfiles/`, symlinked into `$HOME` by GNU Stow. A `Makefile` wraps the common Stow operations and adds an `fzf`-driven importer for new app configs.
3. **Provides maintenance scripts.** Small utilities under `scripts/` and `dotfiles/*/.local/bin/` for VPN setup, post-install repo cloning, disk wiping, ZFS replication, and similar chores.

The provisioning step is resumable: it records progress as marker files, so an interrupted run picks up where it left off. `archsetup --status` shows what's done; `archsetup --fresh` starts over.

## Features

- One-script system provisioning with per-step state tracking and resume
- Pre-flight checks (root, disk space, network) before anything is touched
- Interactive or fully unattended install (via a config file)
- Choice of desktop environment: `dwm` (Xorg + DWM), `hyprland` (Wayland + Hyprland), or `none` (headless/server)
- GPU driver auto-detection (skippable)
- Optional automatic console login for encrypted-root systems
- Builds suckless tools (dwm, dmenu, st, slock) and an Emacs config from configurable Git repos, compiled on a tmpfs RAM disk
- Stow-managed dotfiles split into `common/`, `dwm/`, and `hyprland/` trees
- `Makefile` targets for stow / restow / reset / unstow / import
- Two-theme system (`dupre`, `hudson`) switchable with the `set-theme` script
- VM-based integration test harness (QEMU/KVM) that installs into a throwaway VM and validates the result
- Logs everything to `/var/log/archsetup-*.log`

## Requirements

- A booted Arch Linux live ISO (for the initial OS install), or an already-installed Arch system (to run `archsetup`)
- UEFI firmware (the test harness and typical installs assume UEFI)
- A network connection
- `git`, `make`, `stow`, and `fzf` for the dotfile workflow (`make deps` installs these)
- For the test harness: `qemu-full`, `sshpass`, OVMF firmware, `socat`, and KVM support (`make deps` or `scripts/testing/setup-testing-env.sh`)

## Installation

### 1. Install Arch (live ISO bootstrap)

Boot any Arch Linux ISO from a USB stick and run the bootstrap script:

```sh
curl -s https://<your-domain>/archsetup/init | sh
```

`init` installs `git` and `tmux`, sets a temporary `root` password, and starts `sshd` so you can finish the install remotely. Then it launches `archinstall` to partition the disk and install the base system. (You can also do the base install by hand; `init` is just a convenience.)

### 2. Run archsetup on the installed system

Boot into the new install, clone this repo, and run the provisioning script as root:

```sh
git clone https://github.com/yourusername/archsetup.git
cd archsetup
sudo ./archsetup
```

The script prompts for the username, password, locale, and (on encrypted systems) autologin, unless you supply them via a config file.

#### `archsetup` options

```
Usage: ./archsetup [OPTIONS]

  --config-file PATH    Use a config file for unattended installation
  --fresh               Start fresh, ignore previous progress
  --status              Show installation progress and exit
  --no-gpu-drivers      Skip GPU driver detection/installation
  --autologin           Enable automatic console login
  --no-autologin        Disable automatic console login
  --help, -h            Show this help message
```

### 3. Link the dotfiles

```sh
make stow dwm         # Xorg + DWM
# or
make stow hyprland    # Wayland + Hyprland
```

## Configuration

For an unattended install, copy the template and edit it:

```sh
cp archsetup.conf.example archsetup.conf
./archsetup --config-file archsetup.conf
```

Every field has a default. Set only what you want to change. The config covers:

- `USERNAME` / `PASSWORD`: primary user account (prompted if unset)
- `AUTOLOGIN`: `yes`/`no`, automatic console login (only relevant with encrypted root)
- `NO_GPU_DRIVERS`: `yes` to skip GPU driver auto-detection
- `LOCALE`: e.g. `en_US.UTF-8`
- `DESKTOP_ENV`: `dwm`, `hyprland`, or `none`
- `DWM_REPO`, `DMENU_REPO`, `ST_REPO`, `SLOCK_REPO`, `DOTEMACS_REPO`, `ARCHSETUP_REPO`: Git URLs for the suckless tools, the Emacs config, and this repo

> **Forking note:** The upstream defaults point at the original author's personal Git server and assume a particular username. If you're adapting this for yourself, override the `*_REPO` variables in `archsetup.conf` to point at your own forks. Also review `scripts/post-install.sh` and `scripts/gitrepos.sh` — they clone personal repositories you won't want. The `archsetup` header, `init`'s temporary root password, and a handful of dotfiles (`.gitconfig`, `.ssh/config`, etc.) also carry author-specific values.

## Dotfile Management

Dotfiles live under `dotfiles/` and are stowed into `$HOME` with GNU Stow. The tree splits three ways:

- `dotfiles/common/` — shared by every setup (shell config, `~/.local/bin` scripts, app configs that don't depend on the display server)
- `dotfiles/dwm/` — Xorg/DWM-specific configs and scripts
- `dotfiles/hyprland/` — Wayland/Hyprland-specific configs and scripts

`make stow <de>` links `common` plus the chosen DE tree. The `Makefile` drives all of it:

```
make stow dwm          # Fresh install: link common + dwm
make stow hyprland     # Fresh install: link common + hyprland
make restow dwm        # Refresh links after a git pull (prompts on conflicts)
make reset hyprland    # Resolve conflicts by keeping the repo version
make unstow dwm        # Remove all symlinks
make import common     # fzf-pick app configs and import them into dotfiles/common/
make import dwm        # ...into dotfiles/dwm/
make import hyprland   # ...into dotfiles/hyprland/
make deps              # Install stow, fzf, and the VM-test toolchain
make help              # Full target list
```

`make import` scans `~`, `~/.config`, and `~/.local` for config directories not yet in the repo, lets you multi-select with `fzf`, moves them into the chosen tree, and re-stows so the originals become symlinks. It reminds you to commit afterwards.

### Theme system

Two themes ship in the repo, `dupre` (default) and `hudson`. Switch with the `set-theme` script (installed via the `common` dotfiles). Theme files live under `dotfiles/hyprland/.config/themes/<theme>/` and cover foot, fuzzel, waybar, dunst, hyprlock, and Xresources.

## Desktop Environments

- **DWM (Xorg).** The `dwm` desktop env builds dwm, dmenu, st, and slock from the configured Git repos and links the `dwm` dotfile tree. DWM keybindings live in that fork's `config.def.h`.
- **Hyprland (Wayland).** The `hyprland` desktop env installs Hyprland and links the `hyprland` dotfile tree, including a waybar/foot/fuzzel/dunst/hyprlock stack themed to match.

Pick the desktop env at install time with `DESKTOP_ENV` in the config file (or accept the prompt/default), then link the matching dotfiles with `make stow dwm` or `make stow hyprland`.

## Testing

archsetup ships a VM-based integration test harness under `scripts/testing/`. It uses QEMU/KVM directly (no libvirt) to install Arch into a throwaway VM, run `archsetup` inside it, and validate the result: user creation, stowed dotfiles, AUR helper, desktop environment, services, firewall, and package set.

```sh
make deps              # Install qemu-full, sshpass, OVMF, socat (one-time)
make test              # Create the base VM if needed, then run the full test
make test-keep         # Same, but leave the VM running for manual inspection
make test-vm-base      # (Re)create the base VM only
```

Results land in `test-results/<timestamp>/` (logs, a summary report, and package lists). See `scripts/testing/README.org` for the full workflow, the cleanup and debug helpers, and the validation checks.

## Contributing

This is a personal setup, but bug reports and pull requests are welcome, especially fixes that make it easier to fork. If you're sending a change, keep the `common` / `dwm` / `hyprland` dotfile split intact and run `make test` (or at least `bash -n archsetup`) before opening a PR.

## License

[GPL-3.0](LICENSE)