Skip to content

Installation Guide

This guide covers installation scenarios for workstations, servers, and containers.

Quick Start

🖥️ Workstations (Linux/macOS)

Full setup including dotfiles, system packages, and development tools.

curl -fsSL https://raw.githubusercontent.com/jerdaw/dotfiles/main/scripts/bootstrap | bash

☁️ Servers & Containers

Minimal setup for headless environments (no GUI, no heavy runtimes).

# Automated (from a local clone)
git clone https://github.com/jerdaw/dotfiles.git ~/repos/dotfiles
cd ~/repos/dotfiles
./scripts/bootstrap --server

# Or Dotfiles Only (via chezmoi)
chezmoi init --apply jerdaw/dotfiles --exclude "run_once_*"

Shell Strategy

This project uses a tiered shell policy (see ADR-013):

  • Workstations: zsh is the full interactive shell (plugins, prompt UX, advanced keybindings).
  • Servers/Homelab: bash is the stable baseline by default.
  • Bash Baseline Guarantees: guarded optional tool init, conservative history defaults, and isolated AI-agent history.
  • Both supported: Shared config must stay safe in either shell.

Detailed Installation

Workstation Setup

The default bootstrap script installs: - System Packages: via .chezmoidata.yaml (apt/pacman/brew) - Mise Tools: via mise.toml (node, python, nvim, etc.) - Dotfiles: via chezmoi apply - Rollback Safety: partial plugin/config setup is rolled back automatically if install fails

Interactive Mode: The script will prompt you for: - Sudo password (for system packages) - SSH key generation - Age key generation (for secrets) - Installing zsh if it is missing (recommended for full interactive UX) - Changing the system default login shell to zsh (the prompt is shown again on reruns until the account shell is actually zsh)

Manual Steps: 

git clone https://github.com/jerdaw/dotfiles.git ~/repos/dotfiles
cd ~/repos/dotfiles
./scripts/bootstrap

Failure behavior: - scripts/bootstrap uses an atomic clone flow to avoid partial repo directories on failed clone. - mise run install cleans up partial state (plugin clones + replaced config links) before exiting on error. - Re-running mise run install repairs broken or partial TPM / Antidote checkouts instead of silently skipping them. - In non-interactive mode, missing zsh is not auto-installed; install continues with the supported bash baseline.

Server Setup

Use the --server flag for a lighter footprint. This uses mise-server.toml which excludes: - Desktop apps (WezTerm, VS Code) - Heavy tools (Atuin, Lazygit) - Fonts

./scripts/bootstrap --server

Ansible Integration: For homelabs, use the provided playbook: 

ansible-playbook ansible/setup.yml

Server Profiles

The --profile flag selects a specialized server configuration from mise-profiles/:

./scripts/bootstrap --server --profile docker-host
./scripts/bootstrap --server --profile minimal

See mise-profiles/README.md for the full list.

Windows (WSL2)

Prerequisites: - Windows 10/11 - PowerShell (Admin)

One-Liner: 

Set-ExecutionPolicy Bypass -Scope Process -Force
irm https://raw.githubusercontent.com/jerdaw/dotfiles/main/mise-tasks/setup/provision/windows/bootstrap.ps1 | iex

This installs: - WSL2 & Hyper-V - Winget packages (VS Code, Windows Terminal) - Chocolatey packages

Post-Install:

  1. Open Ubuntu/Debian in WSL
  2. Run the Linux bootstrap command above

Post-Installation

After the bootstrap completes:

  1. Restart Shell:
    • Workstation/full UX: exec zsh
    • Server/baseline: exec bash -l
  2. Verify: Run dots doctor to check health.
  3. Sync History: atuin login (if installed).
  4. Secrets:
    • Copy template: cp dot_secrets.example ~/.secrets
    • Or setup encryption: dots setup-secrets

Uninstalling

To remove symlinks and restore state:

mise run uninstall