feat: initial infrastructure baseline

This commit is contained in:
ja
2026-02-27 16:20:37 +01:00
commit 264cd31ce6
17 changed files with 497 additions and 0 deletions
+24
View File
@@ -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.
+28
View File
@@ -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*
+34
View File
@@ -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)
+40
View File
@@ -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.
+21
View File
@@ -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]
+7
View File
@@ -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"
+4
View File
@@ -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"
+13
View File
@@ -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
+22
View File
@@ -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"
@@ -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.
@@ -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.
+19
View File
@@ -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.
+31
View File
@@ -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. |
+44
View File
@@ -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 <repo-url> 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
```
+46
View File
@@ -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 |
+51
View File
@@ -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
+74
View File
@@ -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"