shell/dotfiles/README.md

# dotfiles

My personal dotfiles and system setup configuration for Linux machines.

## Quick Start

To set up a new machine, run:

```bash
curl -fsSL https://raw.githubusercontent.com/acedanger/shell/main/bootstrap.sh | bash
```

## What's Included

### Package Managers
- [**Nala**](https://gitlab.com/volian/nala): A better front-end for `apt` with parallel downloads and improved interface
- [**VS Code**](https://code.visualstudio.com/): Microsoft's popular code editor
- [**GitHub CLI**](https://cli.github.com/): Official GitHub command-line tool

### Core Packages
- [`git`](https://git-scm.com/): Version control
- [`python3`](https://www.python.org/): Python runtime
- [`wget`](https://www.gnu.org/software/wget/) & [`curl`](https://curl.se/): Download utilities
- [`bat`](https://github.com/sharkdp/bat): A better `cat` with syntax highlighting
- [`cowsay`](https://github.com/piuccio/cowsay): For fun CLI messages
- [`lolcat`](https://github.com/busyloop/lolcat): Colorful terminal output
- [`fzf`](https://github.com/junegunn/fzf): Fuzzy finder
- [`zsh`](https://www.zsh.org/): Better shell
- [`nala`](https://gitlab.com/volian/nala): Better package manager for Debian/Ubuntu
- [`fd-find`](https://github.com/sharkdp/fd): A simple, fast and user-friendly alternative to 'find'

### Shell Setup
- [**Oh My Zsh**](https://ohmyz.sh/): Framework for managing Zsh configuration
- [**Agnoster Theme**](https://github.com/ohmyzsh/ohmyzsh/wiki/Themes#agnoster): Beautiful terminal theme with Git integration

#### Zsh Plugins
1. [`zsh-autosuggestions`](https://github.com/zsh-users/zsh-autosuggestions): Suggests commands as you type based on history
2. [`zsh-syntax-highlighting`](https://github.com/zsh-users/zsh-syntax-highlighting): Syntax highlighting for the shell
3. [`zsh-you-should-use`](https://github.com/MichaelAquilina/zsh-you-should-use): Reminds you of existing aliases
4. [`git`](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git): Git integration and aliases
5. [`docker`](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/docker): Docker commands integration
6. [`docker-compose`](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/docker-compose): Docker Compose integration
7. [`z`](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/z): Quick directory jumping
8. [`ssh`](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/ssh): SSH configuration and shortcuts

### Development Tools
- [**nvm**](https://github.com/nvm-sh/nvm): Node Version Manager for managing Node.js versions
- [**zoxide**](https://github.com/ajeetdsouza/zoxide): Smarter directory navigation (a modern replacement for `z`)
- [**Lazydocker**](https://github.com/jesseduffield/lazydocker): Terminal UI for Docker and Docker Compose, making container management easier
- [**VS Code**](https://code.visualstudio.com/): Code editor with essential extensions

## Features

### Automatic Setup
- Automatically installs and configures all necessary packages and tools
- Sets up Zsh as the default shell
- Configures Nala package manager with optimized mirrors
- Installs and configures Node.js LTS version via nvm
- Installs Lazydocker for Docker container management
- Sets up VS Code with recommended extensions

### Dotfile Management
- Automatically symlinks all configuration files
- Manages Zsh configuration and plugins
- Sets up Git configuration
- Configures custom aliases and functions

### Custom Configurations
- Terminal greeting with fortune and cowsay
- Optimized Zsh history settings
- Improved command-line navigation with zoxide
- Automatic Node.js version switching using .nvmrc

## Installation Process

1. The script will first set up necessary package repositories:
   - Nala package manager
   - VS Code
   - GitHub CLI

2. Install core packages using Nala for better performance

3. Install special tools not available via apt:
   - Lazydocker (Docker TUI manager)

4. Set up the shell environment:
   - Install Zsh and Oh My Zsh
   - Configure Zsh plugins and themes
   - Set up custom aliases and configurations

5. Install development tools:
   - Set up nvm and Node.js
   - Configure zoxide for better navigation
   - Install and configure Git

## Testing

The repository includes a comprehensive testing framework to validate the shell setup process across different environments.

### Docker-Based Testing

Tests are run in isolated Docker containers to ensure consistent, repeatable validation:
- **Ubuntu 24.04 environment**: Tests compatibility with the latest Ubuntu LTS
- **Debian 12 environment**: Tests compatibility with Debian Stable

### Test Coverage

The tests validate:
- Package availability in repositories
- Successful installation of all packages in `packages.list`
- Oh My Zsh installation
- Zsh plugin installation
- Dotfile symlinking
- NVM and Node.js setup

### Running Tests

```bash
# Test your setup on Ubuntu
./run-docker-tests.sh ubuntu

# Test your setup on Debian
./run-docker-tests.sh debian

# Run a full bootstrap test (including installation)
./run-docker-tests.sh full-ubuntu
```

For more details on testing, see [Docker Bootstrap Testing Framework](../docs/docker-bootstrap-testing-framework.md).

## Creating New Aliases

The system supports two types of aliases: **static aliases** (always available) and **dynamic aliases** (conditional based on installed tools).

### Static Aliases (Simple Commands)

For simple command shortcuts that don't require conditional logic:

1. **Edit the base aliases file**:
   ```bash
   nano ~/shell/dotfiles/my-aliases.zsh.original
   ```

2. **Add your alias** in the appropriate section:
   ```bash
   # Example: Add a new Git alias
   alias gst="git status"

   # Example: Add a system alias
   alias ll="ls -la"
   ```

3. **Run the setup script** to regenerate aliases:
   ```bash
   ~/shell/setup/setup.sh
   ```

4. **Reload your shell**:
   ```bash
   source ~/.zshrc
   ```

### Dynamic Aliases (Conditional)

For aliases that depend on whether a tool is installed:

1. **Edit the setup script**:
   ```bash
   nano ~/shell/setup/setup.sh
   ```

2. **Add your conditional alias** after the existing alias setup sections (around line 560):
   ```bash
   # Set up your-tool alias if your-tool is available
   if command -v your-tool &> /dev/null; then
       echo -e "${YELLOW}Setting up your-tool alias...${NC}"
       echo "alias yt=\"your-tool\"" >> "$ALIASES_FILE"
       echo -e "${GREEN}Your-tool alias (yt) configured successfully!${NC}"
   else
       echo -e "${YELLOW}Your-tool not found. Skipping yt alias.${NC}"
   fi
   ```

3. **Run the setup script**:
   ```bash
   ~/shell/setup/setup.sh
   ```

### Alias Categories and Examples

#### 🔧 System Management
```bash
alias update="/home/acedanger/shell/update.sh"
alias ll="ls -laFh --group-directories-first --color=auto"
```

#### 🐳 Docker & Containers
```bash
alias dcdn="docker compose down"
alias dcupd="docker compose up -d"
alias lzd="lazydocker"
alias lzg="lazygit"  # Recently added
```

#### 🎬 Media & Services
```bash
alias plex="/home/acedanger/shell/plex/plex.sh"
alias px="/home/acedanger/shell/plex/plex.sh"
```

#### 🔧 Development Tools
```bash
alias py="python3"
alias gc="git commit"
alias gcm="git commit -m"
```

### Alias Organization Best Practices

1. **Use meaningful names**: Choose alias names that are intuitive and memorable
   - `lzg` for lazygit ✅
   - `x` for some obscure command ❌

2. **Group related aliases**: Keep similar functionality together
   - Docker commands: `dcdn`, `dcupd`, `lzd`
   - Git commands: `gc`, `gcm`, `gpull`, `gpush`

3. **Use emojis for sections**: Help organize and visualize alias categories
   ```bash
   # 🐳 Docker Compose Shortcuts
   # 🎬 Plex Media Server Management
   # 🔧 System Management
   ```

4. **Test before committing**: Always test new aliases to ensure they work correctly

5. **Document complex aliases**: Add comments for non-obvious functionality
   ```bash
   # Opens Plex web interface in default browser
   alias plex-web="xdg-open http://localhost:32400/web"
   ```

### Troubleshooting Aliases

**Alias not working after setup?**
- Restart your terminal or run `source ~/.zshrc`
- Check if the command exists: `which command-name`
- Verify alias was created: `alias alias-name`

**Alias conflicts?**
- Check for existing aliases: `alias | grep alias-name`
- Use `unalias alias-name` to remove conflicting aliases

**Want to remove an alias?**
1. Edit the source file (`my-aliases.zsh.original` or `setup.sh`)
2. Run the setup script again
3. Reload your shell

## Manual Symlink Setup

If you need to manually set up the aliases symlink:

```sh
# Create new symlink
ln -s ~/shell/dotfiles/my-aliases.zsh ~/.oh-my-zsh/custom/aliases.zsh

# If the symlink already exists, use -f to force creation
ln -sf ~/shell/dotfiles/my-aliases.zsh ~/.oh-my-zsh/custom/aliases.zsh
```

## Post-Installation

After installation:
1. Start a new terminal session or run `zsh`
2. The shell will be configured with all plugins and settings
3. You can start using all installed tools and aliases

## Maintenance

To update your setup:
1. Pull the latest changes from the repository
2. Run the setup script again - it's designed to be idempotent
3. Start a new shell session to apply any changes