dotfiles/docs/INSTALLATION.md

# Installation Guide

Complete installation guide for the Modern Dotfiles Management System.

## 🚀 Quick Start (5 Minutes)

### Prerequisites
- Git installed
- Bash or Zsh shell
- Internet connection for package downloads

### One-Line Installation
```bash
cd ~ && git clone https://git.turnersrus.com/razzam21/dotfiles .dotfiles && cd .dotfiles && chmod +x install.sh && ./install.sh
```

### Step-by-Step Installation

1. **Clone the repository**
   ```bash
   cd ~
   git clone https://git.turnersrus.com/razzam21/dotfiles .dotfiles
   cd .dotfiles
   ```

2. **Make installation script executable**
   ```bash
   chmod +x install.sh
   ```

3. **Run the installer**
   ```bash
   ./install.sh
   ```

4. **Follow the interactive prompts**
   - System will auto-detect your machine type
   - Confirm or change the detected profile
   - Wait for package installation to complete

5. **Restart your shell**
   ```bash
   exec $SHELL
   ```

## 🤖 Installation Process Walkthrough

### Profile Detection
```bash
🤖 Machine Profile Detection
==============================
Detected profile: dev

Available profiles:
  server    - Minimal server setup (curl, git, vim, sshuttle, ripgrep, fd)
  dev       - Full development setup (all tools + claude, gemini, docker)
  dev-lite  - Development without heavy packages (no docker)
  personal  - Personal machine (all tools including task-master)
  minimal   - Bare bones (curl, git, vim only)

Use detected profile 'dev'? [Y/n/choose]: 
```

**Profile Detection Logic:**
- **Server**: SSH connection, systemd services, no GUI
- **Development**: Code editors, dev directories, development tools
- **Personal**: Desktop directories, browsers, personal home paths
- **Minimal**: Fallback for unknown environments

### Package Installation
```bash
📦 Checking system packages...
  ✅ curl already installed
  Installing git...
  ✅ git installed successfully
  Installing vim...
  ✅ vim installed successfully
  Installing sshuttle...
  ✅ sshuttle installed successfully

⚡ Checking binary packages...
  Installing claude-code...
  ✅ claude-code installed successfully
  💡 Run 'claude doctor' to verify installation
  Installing gemini-cli...
  ✅ gemini-cli installed successfully

🐙 Checking GitHub packages...
  Installing fzf...
  ✅ fzf installed successfully
  Installing bat...
  ✅ bat installed successfully
  Installing ripgrep...
  ✅ ripgrep installed successfully
  Installing fd...
  ✅ fd installed successfully
  Installing delta...
  ✅ delta installed successfully

🎨 Checking zsh plugins...
  Installing zsh-syntax-highlighting...
  ✅ zsh-syntax-highlighting installed successfully
  Installing zsh-autosuggestions...
  ✅ zsh-autosuggestions installed successfully
```

### Configuration Linking
```bash
🔗 Linking configuration files...
📦 Backing up existing /home/user/.bashrc
🔗 Linked /home/user/.dotfiles/bash/.bashrc -> /home/user/.bashrc
📦 Backing up existing /home/user/.gitconfig
🔗 Linked /home/user/.dotfiles/git/.gitconfig -> /home/user/.gitconfig
🔗 Linked /home/user/.dotfiles/vim/.vimrc -> /home/user/.vimrc
✅ Configured for zsh
```

## 🎯 Profile-Specific Installation

### Server Profile Installation
```bash
# For minimal server environments
./install.sh

# Or force server profile
echo "server" > .machine_profile
./install.sh

# Packages installed:
# - curl, git, vim, sshuttle (system)
# - ripgrep, fd (GitHub tools for log analysis)
# - No development tools, no GUI applications
```

### Development Profile Installation
```bash
# Full development environment
./install.sh

# Or force development profile
echo "dev" > .machine_profile
./install.sh

# Packages installed:
# - All system packages
# - Claude AI, Gemini CLI, Task Master
# - Modern CLI tools (fzf, bat, ripgrep, fd, delta)
# - Docker, docker-compose
# - Zsh plugins and enhancements
```

### Development Lite Profile
```bash
# Development without heavy packages
echo "dev-lite" > .machine_profile
./install.sh

# Packages installed:
# - Development tools (claude, gemini)
# - Modern CLI tools
# - No Docker/containers (lighter footprint)
```

## 🔧 Advanced Installation Options

### Silent Installation
```bash
# Skip interactive prompts (uses auto-detected profile)
DOTFILES_SILENT=true ./install.sh
```

### Force Profile Installation
```bash
# Set specific profile before installation
echo "server" > ~/.dotfiles/.machine_profile
./install.sh
```

### Partial Installation
```bash
# Install only configurations (no packages)
DOTFILES_CONFIG_ONLY=true ./install.sh

# Install only packages (no config linking)
DOTFILES_PACKAGES_ONLY=true ./install.sh
```

### Custom Package Sets
```bash
# Skip optional packages
DOTFILES_SKIP_OPTIONAL=true ./install.sh

# Skip npm packages (if npm not available)
DOTFILES_SKIP_NPM=true ./install.sh

# Skip GitHub packages (if network limited)
DOTFILES_SKIP_GITHUB=true ./install.sh
```

## 🌍 Platform-Specific Instructions

### Ubuntu/Debian
```bash
# Update package list first
sudo apt update

# Install prerequisites if missing
sudo apt install -y git curl

# Standard installation
cd ~ && git clone <repo> .dotfiles && cd .dotfiles && ./install.sh
```

### CentOS/RHEL/Fedora
```bash
# Install prerequisites
sudo yum install -y git curl  # CentOS/RHEL
sudo dnf install -y git curl  # Fedora

# Standard installation
cd ~ && git clone <repo> .dotfiles && cd .dotfiles && ./install.sh
```

### macOS
```bash
# Install Homebrew if not present (installer will do this)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Standard installation
cd ~ && git clone <repo> .dotfiles && cd .dotfiles && ./install.sh
```

### WSL (Windows Subsystem for Linux)
```bash
# WSL automatically detected, uses Linux package methods
cd ~ && git clone <repo> .dotfiles && cd .dotfiles && ./install.sh

# Note: GUI applications may have limited functionality
```

## 🔄 Post-Installation Setup

### Verify Installation
```bash
# Check dotfiles status
dot sync status

# Check installed packages
dot packages

# Check machine profile
dot profile
```

### Test Key Features
```bash
# Test universal aliases
l                    # Should show 'ls -lah'
g                    # Should show git help
..                   # Should change to parent directory

# Test profile-specific tools (if dev profile)
claude --version     # Should show Claude AI version
gemini --help        # Should show Gemini CLI help
fzf --version        # Should show fzf version
```

### Configure Git (First Time Setup)
```bash
# Update git configuration with your details
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

### Configure AI Tools (Development Profiles)
```bash
# Claude AI setup
claude auth login

# Gemini CLI setup (if using)
gemini auth login

# Task Master setup (personal profile)
task-master init
```

## 🛠️ Troubleshooting Installation

### Common Issues

#### Permission Errors
```bash
# If you see permission denied errors:
sudo chown -R $USER:$USER ~/.dotfiles
chmod +x ~/.dotfiles/install.sh
```

#### Package Manager Not Found
```bash
# On minimal systems, install package manager first:
# Ubuntu/Debian: Package manager (apt) should be pre-installed
# CentOS: yum should be pre-installed
# macOS: Installer will install Homebrew automatically
```

#### Network/Firewall Issues
```bash
# If GitHub downloads fail:
DOTFILES_SKIP_GITHUB=true ./install.sh

# If npm installs fail:
DOTFILES_SKIP_NPM=true ./install.sh

# Install manually later:
dot packages install
```

#### Shell Not Supported
```bash
# If you're using a shell other than bash/zsh:
# 1. Install bash or zsh first
# 2. Switch to supported shell: exec bash
# 3. Run installation: ./install.sh
```

### Debug Mode
```bash
# Run installer with debug output
DOTFILES_DEBUG=true ./install.sh

# Check installation logs
cat ~/.dotfiles/.package.log
cat ~/.dotfiles/.profile.log
```

### Manual Recovery
```bash
# If installation fails partway through:
# 1. Check what was installed
dot packages

# 2. Try installing missing packages
dotcheck

# 3. Or reset and start over
dot reset --soft
./install.sh
```

## 🔐 Security Considerations

### What Gets Installed
- **System packages**: Only well-known, trusted packages
- **npm packages**: Official packages from Anthropic, Google
- **GitHub releases**: Downloaded from official repositories
- **No sudo escalation**: Scripts request permission when needed

### Network Access
- **Package managers**: Standard repositories (apt, npm, homebrew)
- **GitHub API**: For latest release information
- **No arbitrary scripts**: All installations use standard package managers

### File Permissions
- **User-level installation**: No system-wide changes required
- **Backup creation**: Existing configs backed up before changes
- **Symlink verification**: Only creates expected symlinks

## 📝 Installation Logs

### Log Locations
```bash
~/.dotfiles/.package.log     # Package installation log
~/.dotfiles/.profile.log     # Profile detection log
~/.dotfiles/.sync.log        # Sync operation log
~/.dotfiles_backup_*         # Configuration backups
```

### Log Analysis
```bash
# Check recent installation activity
tail -20 ~/.dotfiles/.package.log

# Check profile detection reasoning
cat ~/.dotfiles/.profile.log

# Find backup locations
ls -la ~/ | grep dotfiles_backup
```

## 🔄 Next Steps

After successful installation:

1. **Learn the commands**: [Configuration Reference](CONFIGURATION.md)
2. **Customize settings**: Edit files in `~/.dotfiles/shared/`
3. **Set up sync**: Configure git credentials for automatic sync
4. **Explore features**: Try `dot packages check-updates`, `dot profile`, `dot sync status`

---

*Installation complete! Your intelligent dotfiles system is ready to use.*