shell/dotfiles

dotfiles

My personal dotfiles and system setup configuration for Linux machines.

Quick Start

To set up a new machine, run:

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

What's Included

Package Managers

• Nala: A better front-end for apt with parallel downloads and improved interface
• VS Code: Microsoft's popular code editor
• GitHub CLI: Official GitHub command-line tool

Core Packages

• git: Version control
• python3: Python runtime
• wget & curl: Download utilities
• bat: A better cat with syntax highlighting
• cowsay: For fun CLI messages
• lolcat: Colorful terminal output
• fzf: Fuzzy finder
• zsh: Better shell
• nala: Better package manager for Debian/Ubuntu
• fd-find: A simple, fast and user-friendly alternative to 'find'

Shell Setup

• Oh My Zsh: Framework for managing Zsh configuration
• Agnoster Theme: Beautiful terminal theme with Git integration

Zsh Plugins

1. zsh-autosuggestions: Suggests commands as you type based on history
2. zsh-syntax-highlighting: Syntax highlighting for the shell
3. zsh-you-should-use: Reminds you of existing aliases
4. git: Git integration and aliases
5. docker: Docker commands integration
6. docker-compose: Docker Compose integration
7. z: Quick directory jumping
8. ssh: SSH configuration and shortcuts

Development Tools

• nvm: Node Version Manager for managing Node.js versions
• zoxide: Smarter directory navigation (a modern replacement for z)
• Lazydocker: Terminal UI for Docker and Docker Compose, making container management easier
• VS Code: 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

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

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:

   nano ~/shell/dotfiles/my-aliases.zsh.original
   

2. Add your alias in the appropriate section:

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

   ~/shell/setup/setup.sh
   

4. Reload your shell:

   source ~/.zshrc
   

Dynamic Aliases (Conditional)

For aliases that depend on whether a tool is installed:

1. Edit the setup script:

   nano ~/shell/setup/setup.sh
   

2. Add your conditional alias after the existing alias setup sections (around line 560):

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

   ~/shell/setup/setup.sh
   

Alias Categories and Examples

🔧 System Management

alias update="/home/acedanger/shell/update.sh"
alias ll="ls -laFh --group-directories-first --color=auto"

🐳 Docker & Containers

alias dcdn="docker compose down"
alias dcupd="docker compose up -d"
alias lzd="lazydocker"
alias lzg="lazygit"  # Recently added

🎬 Media & Services

alias plex="/home/acedanger/shell/plex/plex.sh"
alias px="/home/acedanger/shell/plex/plex.sh"

🔧 Development Tools

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

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

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

# 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