commit 264cd31ce6c97d738a8dfd181d5fc94a8eaf7365 Author: Jane Alesi Date: Fri Feb 27 16:20:37 2026 +0100 feat: initial infrastructure baseline diff --git a/.clinerules/workstation.md b/.clinerules/workstation.md new file mode 100644 index 0000000..68966db --- /dev/null +++ b/.clinerules/workstation.md @@ -0,0 +1,24 @@ +# Workstation Infrastructure Rules + +## 1. System Changes +- **Preferred Method**: All persistent system changes MUST be implemented via Ansible roles in `ansible/`. +- **Validation**: Before applying Ansible playbooks, always use `--check` mode if possible. +- **Manual Overrides**: Document any manual system changes in `docs/tech/manual-overrides.md`. + +## 2. Maintenance Scripts +- **Standard Header**: All bash scripts MUST start with: + ```bash + #!/bin/bash + set -euo pipefail + ``` +- **Logging**: Scripts should log to stdout for systemd integration and to `/var/log/satway/` if they are long-running. + +## 3. Configuration Management +- **Template First**: Prefer `.j2` templates for configuration files that contain machine-specific variables. +- **Secrets**: NEVER store raw secrets. Use `ansible-vault` for variables in `ansible/vars/`. + +## 4. Documentation (PARA) +- **Product**: System overview, user guides. +- **Tech**: Hardware specs, software versions, network setup. +- **ADR**: Architectural Decision Records for OS choices, partitioning, etc. +- **Learnings**: Incident reports, post-mortems, tips & tricks. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f098e31 --- /dev/null +++ b/.gitignore @@ -0,0 +1,28 @@ +# OS files +.DS_Store +Thumbs.db + +# Secrets +.env +*.key +*.pem +credentials.json +ansible/vault_password + +# Local Cline rules +CLAUDE.local.md +.clinerules/local.md + +# Logs +*.log +.rlm/logs/ + +# Dependencies +node_modules/ +venv/ +.venv/ +__pycache__/ + +# Infrastructure +.terraform/ +*.tfstate* diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..37008be --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,34 @@ +# CLAUDE.md - mw-pfeddersheim-workstation Infrastructure + +## Project Overview +This repository manages the DevOps configuration, software stack, and maintenance scripts for the **mw-pfeddersheim-workstation**. It follows the **saTway** methodology for workstations. + +## Key Directories +- `docs/`: Documentation (Product, Tech, ADR, Learnings) +- `scripts/`: Maintenance and automation scripts +- `config/`: System and application configurations +- `ansible/`: Provisioning and configuration management +- `.clinerules/`: Project-specific AI behavior rules + +## Essential Commands +| Command | Purpose | +|---------|---------| +| `bash scripts/maintenance.sh` | Run standard system maintenance | +| `bash scripts/backup.sh` | Trigger local backup routines | +| `ansible-playbook ansible/workstation.yml` | Apply workstation configuration | + +## Standards +- **Methodology**: Baby Stepsโ„ข, TDD for scripts +- **Security**: Zero-Trust, Gitleaks for secrets +- **Documentation**: All changes documented in `docs/` +- **Scripting**: Bash scripts must use `set -euo pipefail` + +## Guardrails +- **NEVER** commit secrets or private keys +- **ALWAYS** test scripts in a safe manner before full execution +- **PREFER** Ansible for system-wide configuration changes + +## Rules Hierarchy +1. `Rules/` (Global satware AG policies) +2. `.clinerules/` (Project-specific workstation rules) +3. `CLAUDE.md` (This file) diff --git a/README.md b/README.md new file mode 100644 index 0000000..a242ab6 --- /dev/null +++ b/README.md @@ -0,0 +1,40 @@ +# saTway DevOps - mw-pfeddersheim-workstation + +This repository contains the infrastructure-as-code, configuration, and maintenance scripts for the **mw-pfeddersheim-workstation**. + +## ๐Ÿš€ Quick Start + +To apply the current configuration to the workstation: + +```bash +# Apply Ansible configuration +ansible-playbook ansible/workstation.yml + +# Run maintenance +bash scripts/maintenance.sh +``` + +## ๐Ÿ“‚ Structure + +- `ansible/`: Ansible playbooks and roles for system configuration. +- `config/`: Configuration files for various system components. +- `docs/`: Comprehensive documentation following the satware AG PARA structure. +- `scripts/`: System maintenance and automation scripts. + +## ๐Ÿ›  Software Stack + +The workstation is equipped with the following core tools: +- **Languages**: Node.js 22+, Python 3.12+, PHP 8.4 +- **DevOps**: Docker, Ansible, Terraform (planned) +- **Editors**: IntelliJ IDEA, VS Code +- **Shell**: Bash, Git + +## ๐Ÿ“œ Principles + +- **Baby Stepsโ„ข**: Small, verifiable changes. +- **Zero-Trust**: No secrets in the repository, use Ansible Vault or secret managers. +- **TDD**: Write tests for scripts using `bats` (planned). + +## ๐Ÿ“„ License + +Proprietary - satware AG. All rights reserved. diff --git a/ansible/roles/common/tasks/main.yml b/ansible/roles/common/tasks/main.yml new file mode 100644 index 0000000..2a7377f --- /dev/null +++ b/ansible/roles/common/tasks/main.yml @@ -0,0 +1,21 @@ +--- +- name: Optimize kernel parameters + sysctl: + name: "{{ item.name }}" + value: "{{ item.value }}" + state: present + reload: yes + with_items: + - { name: 'vm.swappiness', value: '10' } + - { name: 'fs.inotify.max_user_watches', value: '524288' } + - { name: 'vm.vfs_cache_pressure', value: '50' } + become: yes + tags: [optimization, sysctl] + +- name: Set logind configuration for faster user logins + lineinfile: + path: /etc/systemd/logind.conf + regexp: '^#?KillUserProcesses=' + line: 'KillUserProcesses=no' + become: yes + tags: [systemd, optimization] \ No newline at end of file diff --git a/ansible/vars/main.yml b/ansible/vars/main.yml new file mode 100644 index 0000000..46fe25f --- /dev/null +++ b/ansible/vars/main.yml @@ -0,0 +1,7 @@ +# mw-pfeddersheim-workstation variables +system_user: mw +workspace_root: /home/mw/infrastructure/mw-pfeddersheim-workstation +os_type: archlinux +pnpm_version: "25.6.1" +python_version: "3.14.3" +php_version: "8.5.3" diff --git a/ansible/vars/secrets.yml.example b/ansible/vars/secrets.yml.example new file mode 100644 index 0000000..097b884 --- /dev/null +++ b/ansible/vars/secrets.yml.example @@ -0,0 +1,4 @@ +# EXAMPLE ONLY - DO NOT PUT REAL SECRETS HERE +# USE: ansible-vault create ansible/vars/secrets.yml +# github_token: "your-token-here" +# smtp_password: "your-password-here" diff --git a/ansible/workstation.yml b/ansible/workstation.yml new file mode 100644 index 0000000..8c811b9 --- /dev/null +++ b/ansible/workstation.yml @@ -0,0 +1,13 @@ +--- +- name: Configure mw-pfeddersheim-workstation + hosts: localhost + connection: local + become: true + vars_files: + - vars/main.yml + - vars/secrets.yml + + roles: + - common + - dev-tools + - maintenance diff --git a/config/bashrc.j2 b/config/bashrc.j2 new file mode 100644 index 0000000..3d56e35 --- /dev/null +++ b/config/bashrc.j2 @@ -0,0 +1,22 @@ +# .bashrc template for mw-pfeddersheim-workstation +# Managed by saTway DevOps infra + +# History settings +HISTCONTROL=ignoreboth +HISTSIZE=10000 +HISTFILESIZE=20000 + +# Aliases +alias ll='ls -alF' +alias g='git' +alias d='docker' +alias k='kubectl' +alias main='bash {{ workspace_root }}/scripts/maintenance.sh' + +# Environment +export EDITOR='vim' +export PATH="$HOME/.local/bin:$PATH" + +# saTway indicators +export SATWAY_WORKSTATION="{{ inventory_hostname }}" +export SATWAY_ENV="production" diff --git a/docs/adr/0001-use-ansible-for-configuration.md b/docs/adr/0001-use-ansible-for-configuration.md new file mode 100644 index 0000000..4ef157e --- /dev/null +++ b/docs/adr/0001-use-ansible-for-configuration.md @@ -0,0 +1,21 @@ +# ADR 1: Use Ansible for Workstation Configuration Management + +## Status +Accepted + +## Context +The mw-pfeddersheim-workstation requires a consistent, reproducible configuration. Manual changes lead to "configuration drift" and make it difficult to replicate the environment on new hardware. + +## Decision +We will use **Ansible** as the primary tool for managing system-wide and user-specific configurations. + +## Rationale +- **Agents and Push-based**: No agent needs to be installed on the host (other than Python/SSH). +- **Declarative**: Focuses on state rather than process. +- **Low Barrier to Entry**: Uses YAML and Jinja2 templates, which are well-understood in the satware AG stack. +- **Portability**: Roles can be shared across different workstations if needed. + +## Consequences +- All persistent changes must be scripted in Ansible before application. +- `ansible-playbook` becomes the primary entry point for setup. +- Requires maintaining vault secrets for sensitive configurations. diff --git a/docs/learnings/2026-02-27-initial-setup.md b/docs/learnings/2026-02-27-initial-setup.md new file mode 100644 index 0000000..8ca559f --- /dev/null +++ b/docs/learnings/2026-02-27-initial-setup.md @@ -0,0 +1,18 @@ +# Initial Setup and Baseline - 2026-02-27 + +## Context +Starting the formal infrastructure management for the `mw-pfeddersheim-workstation` repository. The project aim is to manage Michael Wegener's workstation using Ansible 10.x and saTway standards. + +## Initial State +- Repository initialized but no commits yet. +- Base structure for Ansible roles (common, dev-tools, maintenance) exists. +- Maintenance script `scripts/maintenance.sh` present but needs enhancement. +- Goal: Cleanup legacy VS Code remnants and local AI tools. + +## Actions Taken +- Documented initial state. +- Preparing for first baseline commit. + +## Lessons Learned +- Git status confirms all initial files are untracked. +- Structure follows PARA for documentation and standard Ansible layout. \ No newline at end of file diff --git a/docs/product/overview.md b/docs/product/overview.md new file mode 100644 index 0000000..b4acf6c --- /dev/null +++ b/docs/product/overview.md @@ -0,0 +1,19 @@ +# mw-pfeddersheim-workstation Infrastructure Overview + +## Purpose +This repository serves as the single source of truth for the configuration and lifecycle management of Michael Wegener's primary workstation at satware AG (Pfeddersheim location). + +## Goals +1. **Reproducibility**: Ability to restore or rebuild the workstation environment using Ansible. +2. **Reliability**: Automated maintenance and health checks. +3. **Documentation**: Clear record of software stack, decision rationale (ADRs), and tribal knowledge. +4. **Security**: Alignment with Zero-Trust principles and satware AG security standards. + +## Users +- Primarily **Michael Wegener** (MW). +- AI Assistants (Cline/Jane/Junie) for automated task execution and maintenance. + +## Lifecycle +- **Provisioning**: Managed via Ansible playbooks. +- **Maintenance**: Daily/Weekly tasks via `scripts/maintenance.sh`. +- **Documentation**: Continuous updates as the system evolves. diff --git a/docs/tech/performance-tuning.md b/docs/tech/performance-tuning.md new file mode 100644 index 0000000..3262184 --- /dev/null +++ b/docs/tech/performance-tuning.md @@ -0,0 +1,31 @@ +# mw-pfeddersheim-workstation Performance Tuning + +## Overview +This document tracks optimization decisions, system tuning parameters, and cleanup routines implemented for the workstation to ensure maximum resource efficiency and stability. + +## Current System State (2026-02-27) +- **CPU**: AMD/Intel (High core count assumed from load distribution) +- **RAM**: 64GB +- **Storage**: NVMe (77% usage detected) +- **OS**: CachyOS/Arch Linux + +## Optimization Strategies + +### 1. Kernel Parameter Tuning (Ansible) +- **vm.swappiness**: Set to `10` to prefer RAM over swap on the 64GB machine. +- **fs.inotify.max_user_watches**: Increase to `524288` for IDEs and build tools. +- **vm.vfs_cache_pressure**: Set to `50` to improve filesystem cache retention. + +### 2. Storage & Filesystem Cleanup +- **Docker**: Automated pruning of unused images and volumes via `scripts/maintenance.sh`. +- **Journald**: Vacuuming logs older than 7 days or exceeding 500MB. +- **Package Manager**: Maintaining only the last 2 versions of packages in the cache. + +### 3. Service Optimization +- **Ananicy**: (Optional) Use Ananicy-cpp for automatic process prioritizing (CachyOS default usually). + +## Implementation Log + +| Date | Type | Description | +|------|------|-------------| +| 2026-02-27 | Initial | Initial tuning document and strategy established. | \ No newline at end of file diff --git a/docs/tech/setup.md b/docs/tech/setup.md new file mode 100644 index 0000000..2d7c307 --- /dev/null +++ b/docs/tech/setup.md @@ -0,0 +1,44 @@ +# Workstation Setup Guide + +This guide describes how to bootstrap the **mw-pfeddersheim-workstation** infrastructure on a fresh installation. + +## Prerequisites +- Linux (Arch/CachyOS preferred) +- Python 3.12+ +- Git + +## Bootstrap Steps + +1. **Clone the Infrastructure Repo** + ```bash + mkdir -p ~/infrastructure + cd ~/infrastructure + git clone mw-pfeddersheim-workstation + 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 the Playbook** + ```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 + ``` + +5. **Initialize Maintenance** + ```bash + ./scripts/maintenance.sh + ``` diff --git a/docs/tech/software-stack.md b/docs/tech/software-stack.md new file mode 100644 index 0000000..07e5336 --- /dev/null +++ b/docs/tech/software-stack.md @@ -0,0 +1,46 @@ +# Software Stack - mw-pfeddersheim-workstation + +## Core Development Environment + +| Technology | Version | Description | +|------------|---------|-------------| +| **Node.js** | 25.6.1 | Primary JavaScript/TypeScript runtime | +| **Python** | 3.14.3 | Secondary scripting and AI automation language | +| **PHP** | 8.5.3 (CLI) | Legacy and ERP integration language | +| **Ansible** | 2.20.2 (core) | Infrastructure provisioning and configuration | +| **Docker** | 29.2.1 | Containerization and environment isolation | +| **Git** | latest | Version control | + +## OS Context +- **OS**: Linux (CachyOS/Arch Linux based on detected GCC 15 and kernel 6.12) +- **Architecture**: x86_64 + +## Maintenance Policies +- **Updates**: System-wide updates via `pacman` managed through maintenance scripts. +- **Node.js**: Global packages managed via `pnpm`. +- **Python**: Use `uv` for environment management. +- **PHP**: Managed via system package manager, focused on CLI execution. + +## Tool Path Summary +- **Ansible**: `/usr/bin/ansible` +- **Python**: `/usr/bin/python` +- **Docker**: `/usr/bin/docker` + +## Deprecated Software (Pending Cleanup) + +### Microsoft Visual Studio Code (Remnants) +The following remnants of Visual Studio Code / MS IDE components have been identified for review and potential removal to reduce software stack complexity. + +| Type | Path / Identifyer | Description | +|------|-------------------|-------------| +| **Package** | `vscode` | Open Source build of Visual Studio Code (installed via pacman) | +| **Binary** | `/usr/bin/code` | Launcher script for VS Code | +| **Binary** | `/usr/bin/code-oss` | OSS specific launcher script | +| **Config** | `~/.vscode-oss` | Global VS Code OSS configuration and extensions | +| **Theming** | `~/.oh-my-bash/themes/vscode` | VS Code specific oh-my-bash theme | +| **Application Data** | `~/.config/Code - OSS/` | Extensive user data, logs, and cache | +| **Application Data** | `~/.local/share/pipx/venvs/*/lib/python*/site-packages/jupyter_lsp/specs/vscode_*` | Python/Jupyter LSP remnants | +| **Project Data** | `~/Projects/firebird/.vscode` | Local project settings | +| **Project Data** | `~/src/agent-zero/.vscode` | Local project settings | +| **Project Data** | `~/nerve/AutoGPT/.vscode` | Local project settings | +| **Project Data** | `~/agent-zero/data/.vscode` | Local project settings | diff --git a/implementation_plan.md b/implementation_plan.md new file mode 100644 index 0000000..cbc3a67 --- /dev/null +++ b/implementation_plan.md @@ -0,0 +1,51 @@ +# Implementation Plan + +Establish a stable infrastructure baseline for the mw-pfeddersheim-workstation by committing existing files, implementing missing Ansible tasks, and cleaning up legacy tool remnants. + +This plan focuses on transition the repository from an uncommitted state to a managed baseline. It addresses the user's specific request to remove VS Code remnants and local AI tools while setting up a robust maintenance routine through Ansible and shell scripts. The goal is to ensure Michael Wegener's workstation is reproducible and follows the defined saTway standards. + +[Types] +No custom type system changes are required for this infrastructure-heavy task. + +[Files] +Updates existing Ansible roles and creates a new learning log for context restoration. + +Detailed breakdown: +- New files: + - `docs/learnings/2026-02-27-initial-setup.md`: Documentation of the initial repository state and first baseline. + - `ansible/roles/maintenance/tasks/main.yml`: Implementation of system cleanup and maintenance tasks. + - `ansible/roles/dev-tools/tasks/main.yml`: Implementation of development tool management (installation of core tools, removal of legacy ones). +- Existing files to be modified: + - `scripts/maintenance.sh`: Enhanced to handle the `--check` flag and integrate better with Ansible-driven cleanup. +- Configuration updates: + - `.gitignore`: Ensure all relevant system and Ansible files are correctly tracked or ignored. + +[Functions] +No software functions are being implemented; focus is on shell script logic and Ansible tasks. + +Detailed breakdown: +- Modified scripts: + - `scripts/maintenance.sh`: Add parameter parsing for `--check` and implement non-destructive validation mode. + +[Classes] +No classes are used in this project. + +[Dependencies] +Ansible 10.x and standard Arch Linux packages (paccache, checkupdates, journalctl). + +[Implementation Order] +The sequence is designed to establish a git baseline before making system-level changes. + +1. Create initial learning log for documentation. +2. Perform initial git commit of all untracked infrastructure files. +3. Create `feat/initial-baseline` branch for subsequent changes. +4. Implement `ansible/roles/maintenance/tasks/main.yml` including VS Code and AI tool cleanup. +5. Implement `ansible/roles/dev-tools/tasks/main.yml` for core tool validation. +6. Update `scripts/maintenance.sh` to support `--check` mode. +7. Execute Ansible playbook in check mode, then apply. + +task_progress Items: +- [ ] Step 1: Document initial state and create baseline commit +- [ ] Step 2: Implement maintenance role with cleanup tasks (VS Code, AI tools) +- [ ] Step 3: Implement dev-tools role for core workstation software +- [ ] Step 4: Enhance maintenance script and verify via Ansible check mode \ No newline at end of file diff --git a/scripts/maintenance.sh b/scripts/maintenance.sh new file mode 100755 index 0000000..4b95f77 --- /dev/null +++ b/scripts/maintenance.sh @@ -0,0 +1,74 @@ +#!/bin/bash +set -euo pipefail + +# saTway Maintenance Script +# Version: 1.0.0 +# Target: mw-pfeddersheim-workstation + +LOG_FILE="/var/log/satway/maintenance-$(date +%Y%m%d).log" + +# Ensure log directory exists (needs sudo for /var/log usually, or local if not sudo) +# For now we'll log to stdout and optionally a local file if permitted. +# If /var/log/satway is not writeable, fallback to local log. +mkdir -p "$HOME/logs" 2>/dev/null || true +LOCAL_LOG="$HOME/logs/maintenance-$(date +%Y%m%d).log" + +echo "--- Starting saTway Maintenance $(date) ---" | tee -a "$LOCAL_LOG" + +# 1. System Update Check +echo "[1/4] Checking for system updates..." | tee -a "$LOCAL_LOG" +if command -v checkupdates &> /dev/null; then + checkupdates | tee -a "$LOCAL_LOG" +elif command -v pacman &> /dev/null; then + echo "Use 'sudo pacman -Syu' to update system packages." | tee -a "$LOCAL_LOG" +fi + +# 2. System Optimization (Journald & Packages) +echo "[2/6] Optimizing system logs and package cache..." | tee -a "$LOCAL_LOG" +if command -v journalctl &> /dev/null; then + echo "Pruning systemd journal logs..." | tee -a "$LOCAL_LOG" + sudo journalctl --vacuum-time=7d --vacuum-size=500M 2>&1 | tee -a "$LOCAL_LOG" || echo "Journald vacuum failed (requires sudo)" | tee -a "$LOCAL_LOG" +fi + +if command -v paccache &> /dev/null; then + echo "Cleaning Arch package cache (keeping last 2)..." | tee -a "$LOCAL_LOG" + sudo paccache -rk2 2>&1 | tee -a "$LOCAL_LOG" || echo "paccache failed (requires sudo)" | tee -a "$LOCAL_LOG" +fi + +if command -v pacman &> /dev/null; then + echo "Checking for orphaned packages..." | tee -a "$LOCAL_LOG" + ORPHANS=$(pacman -Qtdq) || ORPHANS="" + if [ -n "$ORPHANS" ]; then + echo "Removing orphaned packages: $ORPHANS" | tee -a "$LOCAL_LOG" + sudo pacman -Rns --noconfirm $ORPHANS | tee -a "$LOCAL_LOG" + else + echo "No orphaned packages found." | tee -a "$LOCAL_LOG" + fi +fi + +# 3. Docker Cleanup +if command -v docker &> /dev/null; then + echo "[3/6] Cleaning up Docker resources..." | tee -a "$LOCAL_LOG" + echo "Pruning unused docker data..." | tee -a "$LOCAL_LOG" + # Use prune safely for unused data + docker system prune -f 2>&1 | tee -a "$LOCAL_LOG" + echo "Pruning unused docker volumes (RECLAIMABLE)..." | tee -a "$LOCAL_LOG" + docker volume prune -f 2>&1 | tee -a "$LOCAL_LOG" +fi + +# 4. pnpm/npm check +if command -v pnpm &> /dev/null; then + echo "[4/6] Checking global pnpm packages..." | tee -a "$LOCAL_LOG" + pnpm list -g --depth 0 | tee -a "$LOCAL_LOG" + echo "Suggested: pnpm store prune" | tee -a "$LOCAL_LOG" +fi + +# 5. Git Repos Status +echo "[5/6] Checking infra repo status..." | tee -a "$LOCAL_LOG" +git status | tee -a "$LOCAL_LOG" + +# 6. Disk Space Check (after cleanup) +echo "[6/6] Current disk usage summary:" | tee -a "$LOCAL_LOG" +df -h / | tail -n 1 | tee -a "$LOCAL_LOG" + +echo "--- Maintenance Complete $(date) ---" | tee -a "$LOCAL_LOG"