Dotfiles

Cross-platform dotfiles automation using A-frame architecture with DRY principles and nullable safety patterns.

Quick Start

git clone https://github.com/yourusername/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install

The installer will detect your OS and prompt for profile selection (workstation/home/server).

Supported Platforms

• macOS 10.15+ (Intel and Apple Silicon)
• Linux (Ubuntu, Debian, and derivatives)

Architecture

A-Frame Design

• Main configuration handles shared logic
• OS-specific modules provide platform customizations
• Shared functions eliminate code duplication

Nullable Safety

All operations handle missing files, commands, and environment variables gracefully. Scripts continue execution even when optional components fail.

DRY Optimization

• Shared functions in scripts/common/shared_functions.sh
• Universal package manager interface
• Centralized logging and validation

File Structure

dotfiles/
├── install                           # Main installer script
├── install.conf.yaml                 # Dotbot configuration
├── configs/                          # Configuration files
│   ├── shell/
│   │   ├── zsh/                      # zsh config
│   │   └── <bash>                    # bash config
│   ├── editors/
│   │   ├── nvim/
│   │   └── vscode/
│   ├── git/
│   └── terminal/
├── scripts/                          # Installation scripts
│   ├── common/                       # Shared utilities
│   │   ├── detect_os.sh              # Environment detection
│   │   ├── shared_functions.sh       # Shared functions
│   │   └── logger.sh                 # Error logging
│   ├── macos/                        # macOS-specific scripts
│   └── linux/                        # Linux-specific scripts
└── packages/                         # Package definitions
    ├── macos/
    │   ├── Brewfile.home             # Brewfile for home use
    │   ├── Brewfile.workstation      # Brewfile for office workstation
    │   └── mas.yaml
    └── linux/
        ├── apt.yaml
        └── snap.yaml

Profiles

Workstation

Full development environment with GUI applications, development tools, and IDE configurations.

Home

Personal setup with entertainment tools and reduced development focus.

Server

Minimal configuration optimized for headless environments with security tools and system utilities.

Configuration Management

Shell Configuration (A-Frame)

The zsh configuration uses A-frame architecture:

• ~/.zshrc - Main frame with conditional OS loading
• zshrc.macos - macOS-specific (Antidote plugin manager)
• zshrc.linux - Linux-specific (Oh-My-Zsh)

Environment Variables

Control behavior through environment variables:

# Package installation
ENABLE_HOMEBREW_INSTALL=true
ENABLE_ESSENTIAL_TOOLS=true
ENABLE_BREWFILE=true

# SSH setup
SSH_KEY_TYPE=ed25519
AUTO_GENERATE_KEY=false

# GUI tools
FORCE_GUI_IN_CONTAINER=false

Custom Overrides

Create local customization files that won't be tracked:

• ~/.zshrc.local - Shell customizations
• ~/.gitconfig.local - Git settings
• scripts/.env - Environment variable overrides

Package Management

macOS

• Homebrew for command-line tools
• Homebrew Cask for GUI applications
• Mac App Store via mas

Linux

• APT for system packages
• Snap for GUI applications
• Repository setup for development tools

Package lists are defined in YAML files under packages/ directory.

Development Environment

Included Tools

• Shell: zsh with plugins (Antidote/Oh-My-Zsh)
• Editor: Neovim with configurations
• Terminal: tmux with custom config
• Version Control: Git with sensible defaults
• Languages: Go, Node.js, Python, Ruby (rbenv), Rust

Development Services

Automatically configures and starts:

• PostgreSQL
• Redis
• Docker

Scripts Overview

Core Scripts

• detect_os.sh - Environment and OS detection
• validate_installer.sh - Pre-installation validation
• shared_functions.sh - Common utilities

Setup Scripts

• install_packages.sh - Package installation
• setup_*_defaults.sh - OS-specific system configuration
• setup_shell.sh - Shell environment configuration
• setup_ssh.sh - SSH key and configuration management
• setup_gui_tools.sh - GUI application installation

Installation Options

Standard Installation

./install

Specific Profile

./install --profile server

Validation Only

./install --validate

Force Reinstall

FORCE=true ./install

Customization

Adding Packages

macOS packages - Edit packages/macos/Brewfile.{profile}:

brew "new-package"
cask "new-app"

Linux packages - Edit packages/linux/apt.yaml:

development:
  - new-package

Adding Configurations

1. Place config files in configs/ directory
2. Add symlink in install.conf.yaml:

~/.config/newapp/config:
  path: configs/newapp/config

OS-Specific Configurations

Use conditionals for platform-specific settings:

~/.config/app/config:
  if: '[ "$OS" = "macos" ]'
  path: configs/app/config.macos

Troubleshooting

Installation Fails

1. Run validation: ./install --validate
2. Check OS support and requirements
3. Ensure internet connectivity
4. Verify repository access

Permission Issues

# Fix SSH permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/id_*.pub

# Fix Homebrew permissions (macOS)
sudo chown -R $(whoami) /opt/homebrew

Environment Variables Not Loading

# Source environment manually
source /tmp/dotfiles_env

# Check detection script output
./scripts/common/detect_os.sh

Package Installation Issues

# Update package managers
brew update              # macOS
sudo apt update         # Linux

# Clear package caches
brew cleanup            # macOS
sudo apt autoclean     # Linux

Safety Features

• Idempotent - Safe to run multiple times
• Non-destructive - Won't overwrite existing configurations without confirmation
• Rollback capable - Git-based tracking of changes
• Validation - Pre-installation environment checks
• Graceful degradation - Continues even when components fail

Contributing

1. Follow A-frame architecture principles
2. Use nullable safety patterns
3. Test on both macOS and Linux
4. Update documentation for new features
5. Maintain DRY principles

License

MIT License - see LICENSE file for details.