shell/dotfiles/README.md

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

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 Testing Documentation.

Manual Steps

If you need to manually set up aliases:

# 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