Skip to main content
This page provides detailed information about platform compatibility, system requirements, and tested environments for the dotfiles configuration.

​
Supported Platforms

PlatformSupport LevelNotes
Ubuntu 24.04 LTSPrimaryMain testing environment in CI
Ubuntu 22.04 LTSSupportedFully compatible
Ubuntu 20.04 LTSSupportedFully compatible
Debian 11+SupportedAPT-based distributions
WSL 2 (Ubuntu)PrimaryFull Windows interop support
WSL 1 (Ubuntu)LimitedNo GUI support, limited systemd
Other Debian-basedCommunityShould work, not regularly tested

​
System Requirements

​
Minimum Requirements

  • OS: Ubuntu 20.04+ or Debian 11+
  • Architecture: x86_64 (AMD64)
  • RAM: 512 MB (for basic dotfiles)
  • Disk: 500 MB free space
  • Network: Internet connection required
  • Privileges: sudo access
  • OS: Ubuntu 24.04 LTS or WSL 2
  • Architecture: x86_64 (AMD64)
  • RAM: 2 GB or more
  • Disk: 2 GB free space (for full Ansible packages)
  • Network: Broadband connection
  • Shell: Bash 4.0+

​
Required Dependencies

The bootstrap script automatically installs all required dependencies:

​
Core Dependencies

PackageMinimum VersionPurposeInstallation Method
curl7.x+Download resourcesapt install curl
git2.x+Version controlapt install git
age1.0+File encryptionapt install age
gnupg2.x+GPG key managementapt install gnupg
ansible2.12+Configuration managementPPA: ppa:ansible/ansible

​
Package Managers

ToolRequiredInstallation
APTYesBuilt-in on Debian/Ubuntu
snapOptionalapt install snapd
npmOptionalFallback for Bitwarden CLI

​
Dotfiles Tools

ToolVersionInstallation MethodFallback
chezmoiLatestsnap (classic)Install script to ~/.local/bin
Bitwarden CLILatestsnapnpm (@bitwarden/cli)

​
Tested Environments

​
GitHub Actions CI

All changes are automatically tested in the following environment: 
Container: ubuntu:24.04
Options: --privileged
Python: 3.12
Ansible: Latest stable
CI Pipeline Jobs:
  1. Ansible Lint
    • Validates playbook syntax
    • Checks best practices
    • Verifies collection dependencies
  2. chezmoi Validation
    • Dry-run template initialization
    • Validates template syntax
  3. Integration Tests
    • Bootstrap script execution
    • Ansible playbook application (non-GUI tasks)
    • Dotfiles deployment
    • Package verification
    • File permissions validation
    • age key setup verification

​
Local Testing

Run the full integration test suite: 
bash tests/run-all.sh
Test Coverage:
  • ✅ Dotfiles applied (~/.bash_aliases, ~/.gitconfig, etc.)
  • ✅ Required packages installed
  • ✅ age key exists with 600 permissions
  • ✅ SSH configuration deployed
  • ✅ Ansible playbook idempotence

​
Package Compatibility

​
APT Repositories

The dotfiles add the following external repositories:
RepositoryPurposeKey Management
ppa:ansible/ansibleLatest AnsibleAutomatic via add-apt-repository
Custom repos in all.ymlAdditional softwareGPG key de-armoring via common role

​
Snap Support

Supported:
  • Native Ubuntu installations
  • Some Ubuntu derivatives
Not Supported:
  • WSL 1 (no snapd support)
  • WSL 2 (snapd often doesn’t work in containers)
  • Minimal container environments
Fallback Strategy: If snap is unavailable, the bootstrap script uses:
  • npm for Bitwarden CLI
  • Direct install script for chezmoi

​
Python Compatibility

Python VersionAnsible SupportStatus
Python 3.12✅ YesPrimary (Ubuntu 24.04)
Python 3.10✅ YesSupported (Ubuntu 22.04)
Python 3.8✅ YesSupported (Ubuntu 20.04)
Python 3.6⚠️ LimitedEOL, not recommended
Python 2.x❌ NoNot supported

​
Shell Compatibility

​
Bash

Supported: Bash 4.0+ 
bash --version
# GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)

​
Other Shells

ShellStatusNotes
zshNot configuredWould require separate dotfiles
fishNot configuredWould require separate dotfiles
shPartialBootstrap script uses /bin/bash

​
WSL Compatibility

​
WSL Versions

FeatureWSL 1WSL 2
Dotfiles support✅ Yes✅ Yes
Windows interop✅ Yes✅ Yes
snap support❌ No⚠️ Limited
systemd support❌ No✅ Yes (recent)
GUI apps❌ No✅ Yes (WSLg)
Docker⚠️ Limited✅ Yes
PerformanceGood for I/OBetter for compute

​
WSL Detection

Automatic detection via kernel release: 
# WSL kernel contains "microsoft"
uname -r
# 5.15.90.1-microsoft-standard-WSL2

​
Windows Version Requirements

  • WSL 2: Windows 10 version 1903+ or Windows 11
  • WSLg (GUI): Windows 11 or Windows 10 Build 19044+

​
Desktop Environment Compatibility

​
GNOME

Supported: GNOME 3.36+ Configured Settings:
  • Dark mode (GTK theme)
  • Clock format and visibility
  • Power management
  • Window manager preferences
Requirements:
  • dconf utility
  • Ansible collection: community.general

​
Other Desktop Environments

EnvironmentStatusNotes
KDE PlasmaNot configuredWould require separate Ansible role
XFCENot configuredWould require separate Ansible role
Headless✅ SupportedGUI tasks are skipped
WSLNot applicableNo native DE support

​
Ansible Collection Dependencies

​
Required Collections

# ansible/requirements.yml
collections:
  - name: community.general
    version: ">=5.0.0"
Installation: 
ansible-galaxy collection install -r ansible/requirements.yml

​
Ansible Lint Compatibility

Supported: ansible-lint 6.0+ Installation: 
pip install ansible-core ansible-lint

​
Git Version Compatibility

Git VersionStatusFeatures
2.35+✅ RecommendedConditional includes, full feature set
2.30+✅ SupportedCore functionality
2.20+⚠️ LimitedMay lack some features
< 2.20❌ Not recommendedMissing modern features

​
Bitwarden CLI Compatibility

​
Version Requirements

Minimum: 1.22.0
Recommended: Latest

​
Installation Methods

MethodPriorityPlatforms
snap1st choiceNative Ubuntu
npmFallbackWSL, minimal systems
Verify Installation: 
bw --version
# 2024.x.x

​
Known Limitations

​
Platform Limitations

PlatformLimitationWorkaround
WSL 1No snap supportUses npm/install scripts
WSL 1No systemdNot required for dotfiles
WSL 1No GUIUse Windows GUI apps
ContainersLimited snapdUses fallback methods
ContainersNo systemdUse --skip-tags systemd

​
Feature Limitations

  • GNOME settings: Require active desktop session
  • AWS credentials: Require Bitwarden vault access
  • SSH keys: Require Bitwarden secure notes
  • GUI testing: Skipped in CI environment

​
Upgrade Path

​
Ubuntu LTS Upgrades

When upgrading Ubuntu LTS versions:
  1. Before upgrade: 
    chezmoi archive > ~/dotfiles-backup.tar
  2. Perform system upgrade: 
    sudo do-release-upgrade
  3. After upgrade: 
    # Reinstall Ansible (may need PPA re-add)
sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install -y ansible

# Re-run setup
cd ~/.local/share/chezmoi
ansible-playbook ansible/site.yml
chezmoi apply

​
WSL Upgrades

WSL 1 to WSL 2: 
# In PowerShell (Administrator)
wsl --set-version Ubuntu 2
No dotfiles changes needed; WSL-specific features will continue working.

​
Architecture Support

ArchitectureStatusNotes
x86_64 (AMD64)✅ Fully supportedPrimary architecture
ARM64⚠️ UntestedMay work with ARM-compatible packages
i386❌ Not supported32-bit deprecated

​
Troubleshooting Compatibility

​
Check Your Environment

# OS and version
lsb_release -a

# Kernel (WSL detection)
uname -r

# Architecture
uname -m

# Bash version
bash --version

# Python version
python3 --version

# Git version
git --version

​
Verify Dependencies

# Check if tools are installed
command -v curl && echo "curl: OK"
command -v git && echo "git: OK"
command -v age && echo "age: OK"
command -v ansible && echo "ansible: OK"
command -v chezmoi && echo "chezmoi: OK"
command -v bw && echo "bw: OK"

​
Common Issues

Ansible not found: 
sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install -y ansible
chezmoi not in PATH (fallback install): 
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
Bitwarden CLI not working: 
# Try npm installation
sudo apt install -y nodejs npm
sudo npm install -g @bitwarden/cli

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us