---
description: >-
  Workstation bootstrapping and setup instructions using Ansible.
tags:
  - setup
  - bootstrap
  - ansible
last_updated: '2026-05-20'
---

# 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**
   ```bash
   mkdir -p ~/infrastructure
   cd ~/infrastructure
   git clone https://git.satware.ai/infrastructure/mw-pfeddersheim-workstation.git
   cd mw-pfeddersheim-workstation
   ```

2. **Install Ansible**
   ```bash
   sudo pacman -S ansible
   ```

3. **Configure Secrets**
   ```bash
   # 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](../adr/0002-kernel-and-nvidia-strategy.md) for the rationale.

   ```bash
   # 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)
   ```bash
   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**
   ```bash
   ./scripts/maintenance.sh
   ```