From c1787f773f0081d24004e2abbc14a6dada18833d Mon Sep 17 00:00:00 2001 From: Colin Henry Date: Thu, 5 Feb 2026 20:05:33 -0800 Subject: [PATCH] add elementary os support --- CLAUDE.MD | 178 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- lib/common.sh | 29 ++++++++ provision | 1 + scripts/packages.sh | 6 +- 5 files changed, 213 insertions(+), 3 deletions(-) create mode 100644 CLAUDE.MD diff --git a/CLAUDE.MD b/CLAUDE.MD new file mode 100644 index 0000000..4d18229 --- /dev/null +++ b/CLAUDE.MD @@ -0,0 +1,178 @@ +# CLAUDE.MD - AI Assistant Guide + +## Project Overview + +**System provisioning tool** for macOS and Linux desktop computers. Simple, idempotent shell scripts (~600 LOC) that automate installation of dev tools, GUI apps, and dotfiles. + +**Philosophy**: "JFUI" (Just Use It) - simple, fast, idempotent, self-contained. + +**Main Script**: [provision](provision) - orchestrates all installation steps + +## Structure + +``` +provision/ +├── provision # Main entry point +├── bootstrap # Fresh system bootstrap +├── lib/ +│ ├── common.sh # Platform detection, logging +│ └── package.sh # Package manager abstraction +├── scripts/ +│ ├── packages.sh # CLI tools & X11 (Linux) +│ ├── apps.sh # GUI apps +│ ├── golang.sh # Go from tar.gz +│ ├── plan9port.sh # Plan9 from source +│ ├── user-setup.sh # User & SSH setup +│ ├── macos-defaults.sh # macOS system defaults +│ └── update-xdm.sh # XDM config updater (Linux) +└── config/ # Dotfiles & configs + ├── bashrc, tmux.conf, starship.toml, gitconfig + ├── xinitrc, xsession, Xresources # X11 (Linux) + └── twm/, xdm/ # TWM & XDM configs (Linux) +``` + +## Platforms + +- **macOS**: Homebrew +- **Debian/Ubuntu**: apt (includes Pop!_OS, Linux Mint, other Debian derivatives) +- **elementary OS**: apt (X11/TWM setup skipped - uses native Pantheon desktop) +- **Arch Linux**: pacman + AUR + +## What Gets Installed + +**CLI Tools**: git, curl, wget, tmux, jq, starship, gh, 1Password CLI, Tailscale, Meslo Nerd Font, TPM (tmux plugins) + +**Linux X11** (skipped on elementary OS): twm, slock, xsetroot, feh, xclock, xload, xdm + +**GUI Apps** (skip with `--skip-apps`): VSCodium, 1Password, Obsidian, Chrome, Todoist, Claude Desktop + +**Development** (skip with flags): +- Go → `/usr/local/go` (`--skip-go`) +- Plan9port → `/usr/local/plan9` (`--skip-p9`) + +**Work packages** (`--work`): Slack, Zoom + +**Config**: Bash, tmux, starship, git. Linux: X11/TWM with Dracula theme & 1.5x DPI + +## Usage + +```bash +./provision # Full provision +./provision --skip-apps # No GUI apps +./provision --skip-go # No Go +./provision --skip-p9 # No Plan9 +./provision --work # Include work tools +``` + +Bootstrap fresh system: +```bash +curl -fsSL https://git.sdf.org/jchenry/provision/raw/branch/main/bootstrap | bash +``` + +## Key Implementation + +**Package abstraction** ([lib/package.sh](lib/package.sh)): +```bash +install_package [debian] [arch] [brew] +install_cask # macOS only +install_aur # Arch only +``` + +**Platform detection** ([lib/common.sh](lib/common.sh)): +- `$OS_TYPE`: "macos", "debian", "arch" +- Helpers: `is_macos`, `is_linux`, `is_debian`, `is_arch`, `is_elementary` + +**Logging**: `log_info`, `log_success`, `log_warn`, `log_error` + +**Idempotency**: All scripts check existing installations before proceeding + +## Linux X11/TWM Setup + +**Note**: X11/TWM setup is skipped on elementary OS (uses native Pantheon desktop). + +Complete lightweight X11 environment for Debian/Ubuntu/Arch: +- **XDM**: Display manager with Dracula theme +- **TWM**: Window manager with custom config +- **DPI**: 1.5x default (144). Edit [config/Xresources](config/Xresources), [config/xinitrc](config/xinitrc), [config/xsession](config/xsession) + - 96=1x, 144=1.5x, 192=2x +- **Theme**: Dracula throughout + +Update XDM after changes: +```bash +./scripts/update-xdm.sh +sudo systemctl restart xdm +``` + +## Common Modifications + +**Add CLI tool** - edit [scripts/packages.sh](scripts/packages.sh): +```bash +install_package newtool [debian_name] [arch_name] [brew_name] +``` + +**Add GUI app** - edit [scripts/apps.sh](scripts/apps.sh): +```bash +case "$OS_TYPE" in + macos) install_cask newapp ;; + debian) # debian install ;; + arch) install_aur newapp ;; +esac +``` + +**Work tools** - use `INCLUDE_WORK` pattern: +```bash +if [ "${INCLUDE_WORK:-false}" = true ]; then + # work-specific installs +fi +``` + +**Update dotfiles**: +```bash +# Edit files in config/ +./config/link-dotfiles.sh # Re-symlink +``` + +## Post-Install + +1. `exec $SHELL` - Reload shell +2. Edit `~/.gitconfig` - Set name/email +3. Tmux: `Ctrl+a` then `I` - Install plugins +4. Linux (except elementary OS): `sudo systemctl enable --now xdm` - Enable graphical login + +## Gotchas + +1. **Debian fresh install**: Add user to sudo, then logout/login +2. **macOS**: Install Xcode CLI tools first +3. **Arch AUR**: Script installs AUR helper if missing +4. **XDM changes**: Run [scripts/update-xdm.sh](scripts/update-xdm.sh) + restart service (not applicable to elementary OS) +5. **DPI changes**: Logout/login to apply (not applicable to elementary OS) +6. **elementary OS**: X11/TWM setup automatically skipped - uses native Pantheon desktop + +## Prerequisites + +- git, curl, sudo access (or root) +- macOS: Xcode CLI Tools +- Debian: build-essential (auto-installed) +- Arch: base-devel (auto-installed) + +## Design Principles + +1. **Simple**: 4 main scripts, not 20+ +2. **Fast**: Parallel installs where possible +3. **Idempotent**: Always safe to re-run +4. **Self-contained**: All configs included +5. **Flexible**: Skip components with flags +6. **Minimal deps**: Pure bash +7. **Transparent**: Read scripts to see what happens + +## Error Handling + +- All scripts: `set -euo pipefail` +- Installation failures logged but non-fatal for non-critical tools +- Bootstrap validates prerequisites + +## Testing + +- Test on fresh VMs for each OS +- Re-run scripts to validate idempotency +- Scripts runnable standalone for component testing diff --git a/README.md b/README.md index 902d9a9..f2eb215 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ provision/ ## Supported Platforms - macOS (via Homebrew) -- Debian/Ubuntu (via apt) +- Debian/Ubuntu/elementaryOS (via apt) - Arch Linux (via pacman + AUR) ## After Installation diff --git a/lib/common.sh b/lib/common.sh index 3cefda6..7efb9b9 100755 --- a/lib/common.sh +++ b/lib/common.sh @@ -32,6 +32,25 @@ detect_os() { linux*) if [ -f /etc/arch-release ]; then echo "arch" + elif [ -f /etc/os-release ]; then + # Check for specific distributions + . /etc/os-release + case "$ID" in + elementary|elementaryos) + echo "debian" # elementaryOS is Ubuntu-based + ;; + ubuntu|debian|pop|linuxmint) + echo "debian" + ;; + *) + # Fallback to debian_version check + if [ -f /etc/debian_version ]; then + echo "debian" + else + echo "linux" + fi + ;; + esac elif [ -f /etc/debian_version ]; then echo "debian" else @@ -67,6 +86,16 @@ is_linux() { [[ "$OSTYPE" == "linux"* ]] } +# Check if running on elementary OS +is_elementary() { + if [ -f /etc/os-release ]; then + . /etc/os-release + [[ "$ID" == "elementary" || "$ID" == "elementaryos" ]] + else + return 1 + fi +} + # Create directory if it doesn't exist ensure_dir() { if [ ! -d "$1" ]; then diff --git a/provision b/provision index 0b39a3d..33dc7f3 100755 --- a/provision +++ b/provision @@ -85,6 +85,7 @@ case "$OS_TYPE" in ;; debian) + # Includes Ubuntu, elementaryOS, Pop!_OS, Linux Mint, and other Debian derivatives update_package_cache maybe_sudo apt-get upgrade -y maybe_sudo apt-get install -y build-essential curl wget git diff --git a/scripts/packages.sh b/scripts/packages.sh index 4288f3a..410450c 100755 --- a/scripts/packages.sh +++ b/scripts/packages.sh @@ -172,8 +172,8 @@ case "$OS_TYPE" in ;; esac -# Install X11 utilities (Linux only) -if is_linux; then +# Install X11 utilities (Linux only, skip on elementary OS) +if is_linux && ! is_elementary; then # TWM window manager if command_exists twm; then log_success "twm already installed" @@ -229,6 +229,8 @@ if is_linux; then log_info "Installing xdm" install_package xdm fi +elif is_elementary; then + log_info "Skipping X11/TWM setup on elementary OS (using Pantheon desktop)" fi # Install TPM (Tmux Plugin Manager)