Arch Bootstrap

A Go-based tool for automatic setup of Arch Linux systems.

Features

• TOML Configuration: Simple, readable configuration of all installation steps
• Package Installation: Automatic installation of Pacman packages
• AUR Support: Install yay or paru as AUR helper and use it for AUR packages
• Directories: Create any directory structure with correct user ownership
• Dotfiles: Clone and populate dotfiles automatically with stow (--adopt .)
• Scripts: Download and execute scripts as the real user
• Systemd: Manage Systemd services (enable/disable/start/stop)
• Extra Configurations:
  • Custom US keyboard layout (intl-no-dead keys)
  • Zsh shell setup with default shell configuration
  • Sudo timeout configuration (30 minutes)
• User-Aware: Automatically detects real user when running with sudo
• Dry-Run: Test your configuration without making changes

Installation

# Clone repository
git clone https://github.com/deinusername/archbootstrap.git
cd archbootstrap

# Build
go build -o archbootstrap ./cmd/archbootstrap

# Or install directly
go install ./cmd/archbootstrap

Usage

The tool requires sudo privileges for system operations (pacman, systemd), but automatically detects and uses the real user for user-level operations.

# Run with sudo (recommended)
sudo ./archbootstrap

# With custom configuration file
sudo ./archbootstrap -config /path/to/config.toml

# Dry-run (shows what would be done without executing)
sudo ./archbootstrap -dry-run

# With verbose output
sudo ./archbootstrap -verbose

Note: When running with sudo, the tool automatically:

• Detects the real user (via SUDO_USER environment variable)
• Creates directories with the correct user ownership
• Executes scripts as the real user (not root)
• Clones and manages dotfiles as the real user
• Installs AUR packages as the real user (required by yay/paru)

Configuration

Create a config.toml based on the example in config.example.toml:

Important: In TOML, arrays (packages, aur_packages, dirs) and table-arrays (scripts, systemd) must be defined before the [settings] table!

[settings]
aur_helper = "yay"                          # "yay", "paru" or empty
dotfiles_url = "https://github.com/user/dotfiles.git"
dotfiles_dir = ".dotfiles"
enable_multilib = true
fancy_pacman = true
disable_power_button = true

packages = [
    "git",
    "zsh",
    "stow",
]

aur_packages = [
    "visual-studio-code-bin",
    "brave-bin",
]

dirs = [
    "~/opt/build",
    "~/Documents/projects",
]

[[scripts]]
name = "install-rust.sh"
url = "https://sh.rustup.rs"
execute = true
args = ["-y"]

[[systemd]]
name = "docker.service"
enable = true
start = true
user = false

Configuration Options

[settings]

• aur_helper: Choose between "yay" or "paru" (will be installed automatically)
• dotfiles_url: Git URL to your dotfiles
• dotfiles_dir: Directory name for dotfiles in home directory (default: ".dotfiles")
• hostname: System hostname
• setup_docker: Create docker group and add user
• setup_qemu: Set up QEMU/libvirt groups
• disable_power_button: Disable power button default behavior
• enable_multilib: Enable multilib repository in pacman.conf
• fancy_pacman: Enable colors, ILoveCandy, and ParallelDownloads
• install_myus_layout: Install custom US keyboard layout with intl-no-dead keys
• configure_zsh: Install zsh and set it as default shell
• configure_sudo_timeout: Set sudo timeout to 30 minutes

packages

List of Pacman packages to install from official repositories.

aur_packages

List of AUR packages to install. Requires a configured AUR helper.

dirs

List of directories to create. Supports ~ as an alias for the home directory.

scripts

List of scripts to download and optionally execute:

• name: Name of the script file
• url: URL to download the script from
• execute: Whether to execute the script (true/false)
• args: Optional arguments for the script

systemd

List of Systemd services to configure:

• name: Name of the service
• enable: Enable the service
• disable: Disable the service
• start: Start the service
• stop: Stop the service
• user: User service (true) or system service (false)

Project Structure

archbootstrap/
├── cmd/
│   └── archbootstrap/
│       └── main.go           # Main application
├── internal/
│   ├── config/               # TOML configuration parser
│   ├── pacman/              # Pacman package management
│   ├── aur/                 # AUR helper installation & usage
│   ├── dirs/                # Directory management
│   ├── dotfiles/            # Dotfiles & stow
│   ├── extras/              # Extra configurations (zsh, keyboard layout, etc.)
│   ├── scripts/             # Script download & execution
│   ├── systemd/             # Systemd service management
│   └── user/                # User detection utilities
├── config.example.toml      # Example configuration
├── zenn.toml                # Example personalized configuration
├── go.mod
├── go.sum
└── README.md

Example Workflow

1. Create your config.toml based on the example
2. Test with ./archbootstrap -dry-run -verbose
3. Execute: ./archbootstrap

Dependencies

• Arch Linux (or derivative distribution)
• Go 1.21+ (for building)
• sudo access (required for system operations)

Security Notes

• Always run with sudo: sudo ./archbootstrap
• User operations (directories, scripts, dotfiles, AUR) are automatically performed as the calling user
• System operations (pacman, systemd) require root privileges and are performed via sudo
• AUR helpers (yay/paru) cannot run as root and are automatically executed as the real user

License

MIT