fix: update all branch references from main to dev
Update all URLs and branch references throughout the documentation to use 'dev' as the default branch instead of 'main'. Files updated: - README.md - docs/ONE_LINE_INSTALL.md - docs/WEB_INSTALL_PAGE.html 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Eric Turner
401
docs/INSTALLATION.md
Normal file
401
docs/INSTALLATION.md
Normal file
@@ -0,0 +1,401 @@
|
||||
# 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
|
||||
dotstatus
|
||||
|
||||
# Check installed packages
|
||||
dotpkgs
|
||||
|
||||
# Check machine profile
|
||||
dotprofile
|
||||
```
|
||||
|
||||
### 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:
|
||||
dotinstall
|
||||
```
|
||||
|
||||
#### 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
|
||||
dotpkgs
|
||||
|
||||
# 2. Try installing missing packages
|
||||
dotcheck
|
||||
|
||||
# 3. Or reset and start over
|
||||
dotreset --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 `dotupdatecheck`, `dotprofile`, `dotstatus`
|
||||
|
||||
---
|
||||
|
||||
*Installation complete! Your intelligent dotfiles system is ready to use.*
|
||||
Reference in New Issue
Block a user