A comprehensive, production-ready Ansible-based system for managing workstation and server configurations with support for multiple operating systems, user profiles, and advanced automation features.
# 1. Clone and bootstrap
git clone <repository-url> dotsible
cd dotsible
./scripts/bootstrap.sh
# 2. Validate system
./scripts/validate.sh
# 3. Create backup
./scripts/backup.sh
# 4. Run intelligent dotfiles deployment
./run-dotsible.sh --profile developer --tags dotfiles
# 5. Test conditional deployment
./test-conditional-dotfiles.sh
# 6. Verify installation
./tests/scripts/run_all_tests.sh- Features
- Comprehensive Dotfiles System Enhancement
- Supported Platforms
- Installation
- Usage
- Conditional Dotfiles
- Profiles
- Architecture
- Testing
- Documentation
- Contributing
- Support
- Linux: Ubuntu 20.04+, Debian 11+, Arch Linux
- macOS: 10.15+ (Intel and Apple Silicon)
- Windows: 10/11 (via WSL, Chocolatey, and native tools)
- APT (Debian/Ubuntu) with PPA support
- Pacman (Arch Linux) with AUR integration
- Homebrew (macOS) with Cask support
- Chocolatey (Windows) with package validation
- Git: Advanced configuration with GPG signing, aliases, and hooks
- ZSH: Oh My Zsh integration with themes and plugins
- Vim: Plugin management and custom configurations
- Tmux: Session management with plugin support
- Docker: Container platform with compose integration
- Development Tools: Node.js, Python, Go, Rust, and more
- Minimal: Essential tools for basic usage
- Developer: Complete development environment
- Server: Headless server configuration with monitoring
- Gaming: Gaming and entertainment setup
- Custom: Extensible profile system
- Conditional Dotfiles Deployment: Intelligent configuration selection based on platform, window manager, and environment
- Display Server Support: X11 and Wayland configuration with desktop environment integration
- Window Manager Detection: Automatic deployment of WM-specific configs (i3, Hyprland, Sway, GNOME, KDE)
- Profile-Based Configuration: Minimal/Developer/Enterprise profiles with environment-aware restrictions
- macOS Enterprise Management: MDM compatibility and desktop icon layout preservation
- Cross-Platform Path Resolution: Automatic handling of Unix ~/.config/ vs Windows %APPDATA% paths
- Security Hardening: SSH configuration, firewall rules, and compliance
- Monitoring Integration: Prometheus, Grafana, and log aggregation
- Backup & Recovery: Automated backups with rollback capabilities
- Testing Framework: Comprehensive validation and integration testing
- CI/CD Integration: GitHub Actions, GitLab CI, and Jenkins support
Dotsible now features a revolutionary dotfiles management system that automatically detects and deploys your actual personal configurations instead of placeholder templates. This enhancement provides intelligent auto-detection, GNU Stow integration, and comprehensive validation to ensure your real dotfiles are deployed correctly across all platforms.
The enhanced dotfiles system transforms how Dotsible manages your personal configurations by:
- 🔍 Auto-Detection: Automatically discovers your actual dotfiles repository vs placeholder content
- 🏗️ GNU Stow Integration: Uses GNU Stow as the primary deployment method for robust symlink management
- 🛡️ Intelligent Conflict Resolution: Automatically handles existing files and broken symlinks
- ✅ Comprehensive Validation: Ensures deployed configurations contain your real customizations, not templates
- 🌍 Cross-Platform Support: Works seamlessly across macOS, Linux, and Windows
- 🎯 Conditional Deployment: Smart filtering based on platform, window manager, and environment
- Repository Quality Analysis: Scores dotfiles repositories based on real user content vs template content
- Priority-Based Selection: Automatically chooses the best available dotfiles repository
- GNU Stow Structure Detection: Identifies if your repository is GNU Stow compatible
- Content Validation: Verifies configurations contain actual user customizations
- Warning System: Alerts when placeholder or template content is detected
- Intelligent Conflict Detection: Scans for existing files, symlinks, and directories before deployment
- Categorized Backup System: Separates regular files, broken symlinks, and directories
- Automatic Conflict Removal: Safely removes conflicts based on strategy (force/backup/skip)
- Comprehensive Manifests: Creates detailed logs of all resolution actions with restoration instructions
- Timestamped Storage: Each backup gets a unique timestamp for easy identification
- Comprehensive Flag Support: Implements all major stow command-line options (
--dry-run,--restow,--delete,--adopt) - Dry-Run Validation: Tests deployment before execution to prevent conflicts
- Advanced Operations: Supports restow, unstow, and adopt operations for flexible management
- Error Handling: Provides detailed troubleshooting guidance for failed deployments
- Bidirectional Editing: Maintains GNU Stow's symlink advantages for edit-anywhere capability
- Platform-Specific Filtering: Excludes incompatible applications per operating system
- Window Manager Awareness: Filters based on detected window manager (i3, Hyprland, Sway, etc.)
- Profile-Based Selection: Adapts to minimal/developer/enterprise/server profiles
- Environment-Type Filtering: Adjusts for personal/enterprise/development environments
- Requirements Checking: Validates application prerequisites before deployment
- Symlink Target Analysis: Verifies symlinks point to your actual dotfiles, not placeholders
- Content Validation: Checks that configurations contain real user customizations
- Placeholder Detection: Identifies and reports template/placeholder content
- Structure Preservation: Ensures your original file organization is maintained
- Detailed Reporting: Generates comprehensive validation reports with troubleshooting guidance
- Enhanced Status Reporting: Shows repository type, structure, and content quality
- Visual Progress Indicators: Clear feedback with ✅/❌/⏭️/🔄 status symbols
- Intelligent Deployment Selection: Automatically chooses GNU Stow vs traditional symlinks
- Repository Type Display: Clearly indicates when using actual user dotfiles vs placeholders
- Platform-Aware Detection: Works across macOS, Linux, and Windows
- Path Resolution: Handles different path structures per platform (Unix
~/.config/vs Windows%APPDATA%) - Package Manager Integration: Ensures GNU Stow is available on all platforms
- Conditional Feature Support: Adapts to platform capabilities and limitations
- Conflict Resolution Manifests: Detailed logs of backup and resolution actions
- Validation Reports: Comprehensive analysis of deployment success with troubleshooting steps
- Restoration Instructions: Clear guidance for manual intervention when needed
- Troubleshooting Commands: Ready-to-use commands for issue resolution
The enhanced system follows this intelligent 7-step automated workflow:
- 🔍 Auto-Detection: Scans for and selects your actual dotfiles repository over placeholder content
- 📊 Analysis: Evaluates content quality, structure compatibility, and GNU Stow readiness
- 🛡️ Backup: Intelligently backs up existing files and resolves conflicts automatically
- 🎯 Filtering: Applies conditional deployment based on platform, profile, and environment
- 🔗 Deployment: Uses GNU Stow for robust symlink management with comprehensive flag support
- ✅ Validation: Comprehensively validates deployment success and content authenticity
- 📋 Reporting: Generates detailed reports and troubleshooting guidance
The system now provides comprehensive GNU Stow command-line flag support:
# Core deployment flags
--verbose # Detailed output during operations
--target=<directory> # Specify target directory (default: $HOME)
--dry-run # Test deployment without making changes
# Conflict resolution flags
--restow # Re-stow (replace existing symlinks)
--delete # Remove symlinks (unstow operation)
--adopt # Adopt existing files into stow structure
# Safety and behavior flags
--no-folding # Don't fold directories
--ignore='pattern' # Exclude files matching pattern
--ignore='\.git' # Ignore .git directories
--ignore='\.DS_Store' # Ignore macOS system files
--ignore='README.*' # Ignore documentation filesAdvanced Operations:
- Restow: Update existing symlinks when dotfiles change
- Unstow: Clean removal of symlinks for specific applications
- Adopt: Incorporate existing files into your dotfiles repository
- Dry-Run: Safe testing before making actual changes
✅ Automatic User Dotfiles Detection: System automatically finds and uses your actual dotfiles instead of placeholders ✅ Intelligent Conflict Resolution: Handles existing files without manual intervention ✅ GNU Stow Integration: Primary deployment method with full command-line flag support ✅ Comprehensive Validation: Ensures real user content deployment, not template content ✅ Clean Output Integration: Enhanced reporting with clear visual status indicators ✅ Cross-Platform Compatibility: Works consistently across all supported platforms ✅ Bidirectional Editing: Maintains GNU Stow's symlink advantages for edit-anywhere capability ✅ Zero Manual Configuration: Fully automated detection and deployment process
# Automatic detection and deployment (recommended)
./run-dotsible.sh --profile developer --tags dotfiles
# The system will automatically:
# 1. 🔍 Detect your actual dotfiles repository
# 2. 📊 Analyze content quality and structure
# 3. 🛡️ Backup existing configurations safely
# 4. 🎯 Filter applications for your platform/profile
# 5. 🔗 Deploy using GNU Stow with optimal flags
# 6. ✅ Validate deployment success
# 7. 📋 Generate comprehensive reports
# Manual GNU Stow operations (when needed)
cd /path/to/your/dotfiles && stow --restow zsh nvim tmux
cd /path/to/your/dotfiles && stow --dry-run --verbose alacritty
cd /path/to/your/dotfiles && stow --delete --target=$HOME old_configThe dotsible dotfiles system now automatically deploys your actual personal configurations correctly without any manual intervention, using robust GNU Stow methodology while maintaining comprehensive validation and cross-platform support!
| Platform | Versions | Package Manager | Status |
|---|---|---|---|
| Ubuntu | 20.04, 22.04, 24.04 | APT | ✅ Full Support |
| Debian | 11, 12 | APT | ✅ Full Support |
| Arch Linux | Rolling | Pacman | ✅ Full Support |
| macOS | 10.15+ | Homebrew | ✅ Full Support |
| Windows | 10, 11 | Chocolatey/WSL | 🔶 Partial Support |
| CentOS/RHEL | 8, 9 | YUM/DNF | 🚧 In Development |
| Fedora | 38+ | DNF | 🚧 In Development |
- Python 3.6+
- Ansible 2.9+
- Git
- SSH access (for remote hosts)
- Sudo/Admin privileges (for package installation)
The bootstrap script automatically installs all dependencies:
git clone <repository-url> dotsible
cd dotsible
./scripts/bootstrap.sh# Install dependencies
pip3 install -r requirements.txt
ansible-galaxy install -r requirements.yml
# Create local inventory
cp inventories/local/hosts.yml.example inventories/local/hosts.yml
# Validate installation
./scripts/validate.shdocker run -it --rm \
-v $(pwd):/dotsible \
-v ~/.ssh:/root/.ssh:ro \
dotsible/ansible:latest# Run with default profile (minimal)
ansible-playbook -i inventories/local/hosts.yml site.yml
# Run with specific profile
ansible-playbook -i inventories/local/hosts.yml site.yml -e profile=developer
# Dry run (check what would change)
ansible-playbook -i inventories/local/hosts.yml site.yml --check --diff
# Verbose output
ansible-playbook -i inventories/local/hosts.yml site.yml -vvv# Run specific applications only
ansible-playbook -i inventories/local/hosts.yml site.yml --tags=git,vim
# Skip specific components
ansible-playbook -i inventories/local/hosts.yml site.yml --skip-tags=dotfiles
# Display server configuration
ansible-playbook -i inventories/local/hosts.yml site.yml -e "display_server_preference=wayland desktop_environment=gnome"
# Sway tiling window manager setup
ansible-playbook -i inventories/local/hosts.yml site.yml -e "display_server_preference=wayland desktop_environment=sway profile=developer"
# macOS enterprise setup with desktop layout backup
ansible-playbook -i inventories/local/hosts.yml site.yml -e "profile=developer macos_backup_desktop_layout=true"
# macOS desktop layout restoration
ansible-playbook -i inventories/local/hosts.yml site.yml -e "macos_restore_desktop_layout=true macos_desktop_backup_timestamp=20240101T120000"
# Remote host configuration
ansible-playbook -i inventories/production/hosts.yml site.yml -e profile=server
# Multi-environment deployment
ansible-playbook -i inventories/staging/hosts.yml site.yml --limit=webservers# Create backup before changes
./scripts/backup.sh
# Validate system before running
./scripts/validate.sh
# Emergency rollback
./scripts/rollback.sh
# Test configuration
./tests/scripts/run_all_tests.shDotsible features an intelligent conditional dotfiles deployment system that automatically selects which configurations to deploy based on your platform, window manager, user profile, and environment type. This ensures you get exactly the right configurations for your specific setup while avoiding incompatible or irrelevant configs.
Automatically excludes incompatible configurations:
- macOS: Deploys universal configs + macOS-specific tools, excludes Linux window managers
- Linux: Deploys universal configs + Linux-specific tools, excludes macOS/Windows-only apps
- Windows: Deploys universal configs + Windows-specific tools, excludes Unix-only applications
Intelligently detects and configures window manager-specific tools:
- i3: Deploys i3, polybar, rofi, picom, dunst (X11 required)
- Hyprland: Deploys Hyprland, waybar, wofi, mako (Wayland required)
- Sway: Deploys Sway, waybar, wofi, mako (Wayland required)
- GNOME/KDE: Skips tiling window manager configs, focuses on universal tools
Different application sets based on your usage profile:
- Minimal: Essential tools only (git, vim, zsh)
- Developer: Full development environment (neovim, tmux, starship, alacritty)
- Enterprise: Security-focused with compliance restrictions
- Server: Headless configuration, excludes GUI applications
Adapts configurations for different environments:
- Personal: Full feature set, experimental configs enabled
- Enterprise: Security hardened, restricted external integrations, audit logging
# Automatic detection and intelligent deployment
./run-dotsible.sh --tags dotfiles
# With specific profile
./run-dotsible.sh --profile developer --tags dotfiles
# Enterprise environment with restrictions
./run-dotsible.sh --profile enterprise --environment enterprise --tags dotfiles
# Dry run to see what would be deployed
./run-dotsible.sh --tags dotfiles --check# Force specific window manager detection
./run-dotsible.sh -e "detected_window_manager=i3" --tags dotfiles
# Override display server detection
./run-dotsible.sh -e "detected_display_server=wayland" --tags dotfiles
# Skip conditional filtering (deploy everything)
./run-dotsible.sh -e "skip_conditional_filtering=true" --tags dotfiles# Test conditional deployment logic
./test-conditional-dotfiles.sh
# Validate specific scenarios
ansible-playbook test-conditional-only.yml --check
# Test with different profiles
./run-dotsible.sh --profile minimal --tags dotfiles --checkThe conditional system handles these common scenarios automatically:
Detected Environment: macOS + Developer Profile + Personal Environment
./run-dotsible.sh --profile developer --tags dotfilesDeployed Applications:
- ✅ Universal: git, neovim, tmux, zsh, starship, alacritty, ranger
- ✅ macOS-specific: hammerspoon, karabiner, rectangle, iterm2
- ❌ Excluded: i3, polybar, rofi (Linux window managers)
- ❌ Excluded: powershell, windows-terminal (Windows-only)
Detected Environment: Arch Linux + i3 + X11 + Developer Profile
./run-dotsible.sh --profile developer --tags dotfiles
# Auto-detects: detected_window_manager=i3, detected_display_server=x11Deployed Applications:
- ✅ Universal: git, neovim, tmux, zsh, starship, alacritty, ranger
- ✅ Linux-specific: i3, polybar, rofi, picom, dunst
- ✅ X11-compatible: All X11-based applications
- ❌ Excluded: hyprland, waybar, wofi (Wayland-only)
- ❌ Excluded: hammerspoon, karabiner (macOS-only)
Detected Environment: Arch Linux + Hyprland + Wayland + Developer Profile
./run-dotsible.sh --profile developer --tags dotfiles
# Auto-detects: detected_window_manager=hyprland, detected_display_server=waylandDeployed Applications:
- ✅ Universal: git, neovim, tmux, zsh, starship, alacritty, ranger
- ✅ Wayland-specific: hyprland, waybar, wofi, mako, swaync
- ❌ Excluded: i3, polybar, rofi, picom (X11-only)
- ❌ Excluded: Windows/macOS-specific applications
Detected Environment: Windows + Enterprise Profile + Enterprise Environment
./run-dotsible.sh --profile enterprise --environment enterprise --tags dotfilesDeployed Applications:
- ✅ Universal: git, neovim (Windows paths)
- ✅ Windows-specific: powershell, windows-terminal
- ✅ Enterprise-hardened: Compliance mode enabled, external plugins disabled
- ❌ Excluded: All Linux/macOS window managers and tools
- ❌ Excluded: Social integrations, experimental features
Detected Environment: Ubuntu + Server Profile + SSH Session + No GUI
./run-dotsible.sh --profile server --tags dotfiles
# Auto-detects: is_ssh_session=true, detected_display_server=noneDeployed Applications:
- ✅ Essential: git, vim, tmux, zsh (minimal server configs)
- ✅ Server-optimized: Lightweight configurations, no GUI dependencies
- ❌ Excluded: All GUI applications and window managers
- ❌ Excluded: Desktop-specific tools and themes
The conditional system integrates seamlessly with dotsible's clean output patterns:
🧠 CONDITIONAL DEPLOYMENT ENGINE
📋 DEPLOYMENT PLAN
🎯 Platform: Darwin (macOS)
🖥️ Display Server: Aqua
🪟 Window Manager: None
👤 Profile: Developer
🏢 Environment: Personal
📦 Applications to Deploy (8):
• ✅ git
• ✅ neovim
• ✅ tmux
• ✅ zsh
• ✅ starship
• ✅ alacritty
• ✅ hammerspoon
• ✅ karabiner
⏭️ Excluded Applications (12):
• ❌ i3 (Linux-only application on Darwin)
• ❌ polybar (X11-only application with Aqua display server)
• ❌ hyprland (Wayland-only application with Aqua display server)
Automatic handling of platform-specific configuration paths:
- Unix/Linux/macOS:
~/.config/,~/.local/share/,~/.local/bin/ - Windows:
%LOCALAPPDATA%/,%APPDATA%/,%USERPROFILE%/bin/
Maintains GNU Stow-like bidirectional editing capabilities:
- Unix/macOS: Directory-level symlinks (
~/.config/nvim→~/dotsible/files/dotfiles/nvim) - Windows: Copy with backup strategy due to symlink limitations
- Result: Edit configs in either location, changes reflect in both
Preserves existing Model Context Protocol (MCP) package management:
- Maintains compatibility with
@modelcontextprotocol/server-brave-search - Supports
@modelcontextprotocol/server-puppeteerandfirecrawl-mcp - Integrates with existing development environment workflows
# Override automatic detection
export DOTSIBLE_WINDOW_MANAGER="i3"
export DOTSIBLE_DISPLAY_SERVER="x11"
export DOTSIBLE_ENVIRONMENT="enterprise"
# Skip specific checks
export DOTSIBLE_SKIP_WM_DETECTION="true"
export DOTSIBLE_SKIP_CONDITIONAL="false"# In group_vars/all/dotfiles.yml
dotfiles:
conditional_deployment: true
bidirectional_editing: true
symlink_strategy: "force" # force, skip, backup
# Override compatibility matrix
dotfiles_application_compatibility:
universal:
- git
- neovim
- custom_app# In group_vars/all/profiles.yml
profiles:
custom_developer:
applications:
- git
- neovim
- tmux
- custom_tools
window_manager_support: true
gui_applications: true
security_focused: falseThe conditional dotfiles system provides several key advantages:
- 🎯 Precision: Deploy only relevant configurations for your specific environment
- 🚀 Speed: Faster deployments by skipping incompatible applications
- 🛡️ Safety: Prevents configuration conflicts and system issues
- 🔧 Flexibility: Easy manual overrides when needed
- 📊 Transparency: Clear reporting of what's deployed and why
- 🔄 Maintainability: Centralized logic that's easy to extend and modify
- 🌍 Universality: Works consistently across all supported platforms
For detailed implementation information, see the Conditional Dotfiles Implementation Guide.
Dotsible includes an intelligent backup system that automatically protects your existing configurations before making any changes. This ensures you can always recover your previous settings if needed.
- Pre-deployment Scanning: Checks for existing files that would conflict with symlink creation
- Intelligent Backup: Only backs up files that aren't already symlinks to dotsible
- Timestamped Storage: Each backup gets a unique timestamp for easy identification
- Manifest Generation: Detailed logs of what was backed up and how to restore it
All backups are stored in ~/.dotsible/backups/ with the following structure:
~/.dotsible/backups/
├── 1749419703/ # Timestamp-based backup directory
│ ├── .gitconfig.backup # Backed up files
│ ├── nvim_dir.backup/ # Backed up directories
│ └── git_backup_manifest.txt # Recovery instructions
└── 1749420156/ # Another backup session
└── ...
# Backup happens automatically during deployment
./run-dotsible.sh --profile enterprise --tags dotfiles
# Example output:
# 🔄 CONFLICT RESOLUTION
# ✅ Conflicts resolved - ready for symlink creation
# Files Backed Up: 2
# Backup Location: ~/.dotsible/backups/1749419703# View backup directories
ls -la ~/.dotsible/backups/
# Check what was backed up
cat ~/.dotsible/backups/*/git_backup_manifest.txt
# Restore from backup (manual process)
cp ~/.dotsible/backups/1749419703/*.backup ~/Each backup includes a manifest file with recovery instructions:
git Dotfiles Backup Manifest
=====================================
Backup Date: 2025-06-08T21:55:03Z
Application: git
Host: localhost
User: mdrozrosario
Files Backed Up:
- /Users/mdrozrosario/.gitconfig → ~/.dotsible/backups/1749419703/.gitconfig.backup
Recovery Instructions:
To restore these files, copy them back from this backup directory:
cp ~/.dotsible/backups/1749419703/*.backup ~/
# In roles/dotfiles/vars/main.yml
dotfiles:
backup_existing: true # Enable/disable backup
backup_directory: "~/.dotsible/backups"
symlink_strategy: "force" # force, skip, backup# Clean up old backups (manual)
find ~/.dotsible/backups -type d -mtime +30 -exec rm -rf {} \;
# Or use the generated cleanup script
~/.dotsible/backups/cleanup_old_backups.sh- ✅ Regular files that would conflict with symlinks
- ✅ Directories that would conflict with symlinks
- ❌ Existing symlinks pointing to dotsible (skipped)
- ❌ Non-existent files (nothing to backup)
- Scan: Check target locations for existing files/directories
- Filter: Skip files that are already dotsible symlinks
- Backup: Copy conflicting files to timestamped backup directory
- Remove: Remove original files to make way for symlinks
- Deploy: Create new symlinks to dotsible configurations
- Manifest: Generate recovery instructions
# Emergency rollback process
# 1. Remove dotsible symlinks
rm ~/.gitconfig ~/.zshrc ~/.tmux.conf
rm -rf ~/.config/nvim ~/.config/alacritty
# 2. Restore from backup
cp ~/.dotsible/backups/TIMESTAMP/*.backup ~/
cp -r ~/.dotsible/backups/TIMESTAMP/*_dir.backup/* ~/.config/
# 3. Verify restoration
ls -la ~/.gitconfig ~/.zshrc ~/.config/nvim/The backup system integrates seamlessly with dotsible's other features:
- Conditional Deployment: Only backs up files for applications being deployed
- Profile Awareness: Respects profile-specific application filtering
- Cross-Platform: Works on macOS, Linux, and Windows
- Clean Output: Provides clear status messages during backup operations
- Idempotent: Running deployment multiple times won't create duplicate backups
Essential tools for basic system operation:
- Git, Vim, basic shell configuration
- Essential packages and utilities
- Minimal resource footprint
ansible-playbook -i inventories/local/hosts.yml site.yml -e profile=minimalComplete development environment:
- All minimal profile features
- Development tools (Node.js, Python, Docker)
- Advanced shell (Oh My Zsh, Powerlevel10k)
- Code editors and IDEs
- Git advanced configuration
- Tmux with plugins
ansible-playbook -i inventories/local/hosts.yml site.yml -e profile=developerHeadless server configuration:
- System monitoring and alerting
- Security hardening and compliance
- Log management and rotation
- Backup automation
- Service management and optimization
ansible-playbook -i inventories/local/hosts.yml site.yml -e profile=serverGaming and entertainment setup:
- Steam, Lutris, and gaming platforms
- Media applications and codecs
- Graphics optimizations
- Gaming-specific tools and utilities
ansible-playbook -i inventories/local/hosts.yml site.yml -e profile=gamingCreate your own profiles by editing group_vars/all/profiles.yml:
profiles:
data_scientist:
applications:
- git
- vim
- python3
- jupyter
- r-lang
features:
- python_data_stack
- r_environment
- jupyter_lab
packages:
- python3-pip
- r-base
- postgresql-clientdotsible/
├── 📄 ansible.cfg # Ansible configuration
├── 📄 site.yml # Main playbook
├── 📄 requirements.yml # Ansible Galaxy requirements
├── 📁 inventories/ # Host inventories
│ ├── 📁 local/ # Local machine inventory
│ ├── 📁 development/ # Development environment
│ └── 📁 production/ # Production environment
├── 📁 group_vars/ # Group variables
│ ├── 📁 all/ # Variables for all hosts
│ ├── 📄 ubuntu.yml # Ubuntu-specific variables
│ ├── 📄 archlinux.yml # Arch Linux-specific variables
│ ├── 📄 macos.yml # macOS-specific variables
│ └── 📄 windows.yml # Windows-specific variables
├── 📁 roles/ # Ansible roles
│ ├── 📁 common/ # Common system setup
│ ├── 📁 package_manager/ # Cross-platform package management
│ ├── 📁 applications/ # Application-specific roles
│ │ ├── 📁 git/ # Git configuration
│ │ ├── 📁 vim/ # Vim setup
│ │ ├── 📁 zsh/ # ZSH with Oh My Zsh
│ │ └── 📁 tmux/ # Tmux configuration
│ ├── 📁 profiles/ # User profile roles
│ └── 📁 dotfiles/ # Dotfiles management
├── 📁 playbooks/ # Specific playbooks
├── 📁 templates/ # Jinja2 templates
├── 📁 scripts/ # Utility scripts
│ ├── 📄 bootstrap.sh # System bootstrap
│ ├── 📄 validate.sh # Pre-run validation
│ ├── 📄 backup.sh # System backup
│ └── 📄 rollback.sh # Emergency rollback
├── 📁 tests/ # Testing framework
│ ├── 📁 roles/ # Role-specific tests
│ ├── 📁 integration/ # Integration tests
│ ├── 📁 validation/ # Syntax validation
│ └── 📁 scripts/ # Test automation
├── 📁 docs/ # Documentation
│ ├── 📄 USAGE.md # Detailed usage guide
│ ├── 📄 EXTENDING.md # Extension guide
│ ├── 📄 TESTING.md # Testing procedures
│ └── 📄 TROUBLESHOOTING.md # Common issues
└── 📁 examples/ # Configuration examples
├── 📁 configurations/ # Complete setups
├── 📁 profiles/ # Custom profiles
└── 📁 integrations/ # CI/CD and cloud integrations
Cross-platform package management with automatic detection:
- APT configuration and repository management
- Pacman with AUR helper integration
- Homebrew with Cask support
- Chocolatey with package validation
Intelligent dotfiles deployment with advanced conditional logic:
- Platform-aware filtering: Automatic exclusion of incompatible configurations
- Window manager detection: Smart deployment of WM-specific configs (i3, Hyprland, Sway)
- Profile-based selection: Different application sets for minimal/developer/enterprise profiles
- Environment type awareness: Personal vs enterprise configurations with security restrictions
- Cross-platform path resolution: Automatic Unix ~/.config/ vs Windows %APPDATA% handling
- Bidirectional editing: GNU Stow-like symlink management with edit-anywhere capability
- Clean output integration: Visual status indicators (✅/❌/⏭️/🔄) for deployment status
- Template-based configuration: Dynamic config generation based on environment
- Automated backup and versioning: Safe deployment with rollback capabilities
Built-in security features:
- SSH hardening and key management
- Firewall configuration
- User account policies
- System audit and compliance checks
Dotsible includes a comprehensive testing framework:
# Run all tests
./tests/scripts/run_all_tests.sh
# Syntax validation
./tests/scripts/validate_syntax.sh
# Role-specific tests
ansible-playbook -i tests/inventories/test.yml tests/roles/test-git.yml
# Integration tests
ansible-playbook -i tests/inventories/test.yml tests/integration/cross-platform.yml- Syntax Tests: YAML and Ansible playbook validation
- Role Tests: Individual application functionality
- Integration Tests: Cross-platform compatibility
- Performance Tests: Execution time and resource usage
- Security Tests: Configuration security validation
GitHub Actions workflow for automated testing:
# .github/workflows/test.yml
name: Dotsible Tests
on: [push, pull_request]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest]
profile: [minimal, developer]
steps:
- uses: actions/checkout@v3
- name: Run tests
run: ./tests/scripts/run_all_tests.sh- USAGE.md - Comprehensive usage guide with examples
- EXTENDING.md - Adding new applications and OS support
- TESTING.md - Testing procedures and framework
- TROUBLESHOOTING.md - Common issues and solutions
- ARCHITECTURE.md - Detailed system architecture
- Conditional Dotfiles - Intelligent dotfiles deployment system
- Display Servers - X11 and Wayland configuration guide
- macOS Enterprise - Enterprise macOS management with MDM compatibility
- Package Management - Cross-platform package handling
- Dotfiles Integration - Traditional dotfiles management system
- Security Hardening - Security configuration guide
- Performance Tuning - Optimization recommendations
- Configuration Examples - Real-world setup examples
- Custom Profiles - Profile creation templates
- Integration Examples - CI/CD and cloud setups
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run the test suite:
./tests/scripts/run_all_tests.sh - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
# Clone your fork
git clone https://github.com/yourusername/dotsible.git
cd dotsible
# Install development dependencies
pip3 install -r requirements-dev.txt
# Run pre-commit hooks
pre-commit install
# Run tests
./tests/scripts/run_all_tests.sh- 🆕 New Applications: Add support for additional tools
- 🖥 Operating Systems: Extend platform support
- 🧪 Testing: Improve test coverage and automation
- 📚 Documentation: Enhance guides and examples
- 🔧 Features: Add new functionality and improvements
- 🐛 Bug Fixes: Resolve issues and edge cases
- 📖 Documentation: Check the docs/ directory
- 🐛 Issues: Create GitHub issues for bugs
- 💬 Discussions: Use GitHub discussions for questions
- 📧 Email: Contact maintainers for security issues
- 💬 Discord: Join our Discord server
- 🐦 Twitter: Follow @dotsible
- 📺 YouTube: Dotsible Channel for tutorials
- 🏢 Enterprise Support: Available for organizations
- 🎓 Training: Custom training sessions
- 🔧 Consulting: Implementation and customization services
- v2.1: Windows native support improvements
- v2.2: Container orchestration integration
- v2.3: Cloud provider automation
- v3.0: GUI management interface
- 🌟 Stars: Growing community support
- 🍴 Forks: Active development ecosystem
- 🐛 Issues: Responsive issue resolution
- 📈 Downloads: Increasing adoption
- 🥇 Best Ansible Project 2024 - DevOps Awards
- ⭐ Featured Project - Ansible Galaxy
- 🎖 Community Choice - Open Source Awards
This project is licensed under the MIT License - see the LICENSE file for details.
- Ansible Community for excellent automation tools
- Oh My Zsh Project for shell enhancements
- Homebrew Team for macOS package management
- All Contributors who make this project possible
- Ansible - IT automation platform
- Oh My Zsh - ZSH framework
- Homebrew - macOS package manager
- Chocolatey - Windows package manager
⭐ Star this repository if you find it useful!
🚀 Happy Configuring with Dotsible!