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

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

   cd ~
   git clone https://git.turnersrus.com/razzam21/dotfiles .dotfiles
   cd .dotfiles
   

2. Make installation script executable

   chmod +x install.sh
   

3. Run the installer

   ./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

   exec $SHELL
   

🤖 Installation Process Walkthrough

Profile Detection

🤖 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

📦 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

🔗 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

# 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

# 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

# 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

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

Force Profile Installation

# Set specific profile before installation
echo "server" > ~/.dotfiles/.machine_profile
./install.sh

Partial Installation

# 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

# 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

# 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

# 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

# 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)

# 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

# Check dotfiles status
dot sync status

# Check installed packages
dot packages

# Check machine profile
dot profile

Test Key Features

# 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)

# 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)

# 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

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

Package Manager Not Found

# 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

# 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

# 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

# Run installer with debug output
DOTFILES_DEBUG=true ./install.sh

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

Manual Recovery

# 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

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

Log Analysis

# 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
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.