mw-pfeddersheim-workstation/docs/tech/setup.md

description, tags, last_updated

description	tags	last_updated
Workstation bootstrapping and setup instructions using Ansible.	setup bootstrap ansible	2026-05-18

Workstation Setup Guide

This guide describes how to bootstrap the mw-pfeddersheim-workstation infrastructure on a fresh installation.

Prerequisites

• Linux (Manjaro/Arch Linux)
• Python 3.12+
• Git

Bootstrap Steps

1. Clone the Infrastructure Repo

   mkdir -p ~/infrastructure
   cd ~/infrastructure
   git clone https://git.satware.ai/infrastructure/mw-pfeddersheim-workstation.git
   cd mw-pfeddersheim-workstation
   

2. Install Ansible

   sudo pacman -S ansible
   

3. Configure Secrets

   # Create a vault password file (do not commit!)
   echo "your-strong-password" > ansible/vault_password
   
   # Create secrets file
   ansible-vault create ansible/vars/secrets.yml
   

4. Run system upgrade & kernel install (preparation for Hyprland/Wayland)

   This step runs the dedicated system-upgrade role: full pacman -Syu, dual-kernel install (linux612 LTS + linux70 stable), and NVIDIA driver migration from the pinned 575xx branch to mainline 595.71. Always preview first with --check. See ADR 0002 for the rationale.

   # Preview — never run the live playbook before --check is clean
   ansible-playbook -i localhost, -c local \
     --vault-password-file ansible/vault_password \
     ansible/workstation.yml --check --tags system-upgrade
   
   # Apply (will install/remove packages and regenerate GRUB)
   ansible-playbook -i localhost, -c local \
     --vault-password-file ansible/vault_password \
     ansible/workstation.yml --tags system-upgrade
   

   After it finishes, reboot and select linux70 from the GRUB menu before continuing to step 5. Verify with uname -r (expect 7.0.x) and nvidia-smi (expect driver 595.71.05).

5. Run the Playbook (remaining roles: common, dev-tools, maintenance)

   ansible-playbook -i localhost, -c local --vault-password-file ansible/vault_password ansible/workstation.yml --check
   # If check passes:
   ansible-playbook -i localhost, -c local --vault-password-file ansible/vault_password ansible/workstation.yml
   

6. Initialize Maintenance

   ./scripts/maintenance.sh