dotfiles & system setup

👀 Check Out My Blog Post on this Project! (Outdated)

I have a blog post about this project here.

⚠️ NOTE: It's outdated as previously everything including dotfiles was setup using Ansible. Now, we have a mix of Stow + Ansible.

Three layers, clear boundaries: Stow for dotfiles, Ansible for system setup, mise for developer tools.

• Stow manages all configuration files (dotfiles). Adding a new tool config is as simple as creating a directory and running stow.
• Ansible handles system-level setup: base packages, services, Docker, fonts, terminal emulator, shell defaults - anything that is OS-specific or needs root.
• mise manages developer tools and language runtimes (Go, Node, Python, Rust, Neovim, ripgrep, fzf, lazygit, etc.). One config file, works the same on Arch, Fedora, and Ubuntu - no more per-distro task files for dev tools.

How it works

New machine setup (one command):

bash -c "$(curl -fsSL https://raw.githubusercontent.com/shricodev/dotfiles/main/bin/dotfiles)"

This auto-detects your OS, installs Ansible, runs the playbook (which installs all packages and deploys dotfiles via stow).

Day-to-day dotfiles (no ansible needed):

# edit configs in place (already symlinked)
vim dots/nvim/.config/nvim/init.lua

# add a new tool
mkdir -p dots/wezterm/.config/wezterm
# add your config files...
stow -d dots -t ~ wezterm

📽️ Demo (Outdated)

You can find the demo video setting up this dotfiles configuration on multiple ubuntu homelabs here: Link

Requirements

• Git
• Supported OS: Arch Linux, Ubuntu, Fedora
• (Optional) Ansible for system setup (auto-installed by the bootstrap script)
• (Optional) Docker for testing in a container

Ansible Version Notes

Compatible with Ansible 2.20+. All system facts are accessed via ansible_facts["distribution"], ansible_facts["user_dir"], etc.

Project Structure

.
├── dots/                      # Stow packages (dotfiles)
│   ├── mise/                  #   ~/.config/mise/config.toml (dev tool list)
│   ├── nvim/                  #   ~/.config/nvim/
│   ├── tmux/                  #   ~/.config/tmux/
│   ├── fish/                  #   ~/.config/fish/
│   ├── kitty/                 #   ~/.config/kitty/
│   ├── ghostty/               #   ~/.config/ghostty/
│   ├── alacritty/             #   ~/.config/alacritty/
│   ├── lazygit/               #   ~/.config/lazygit/
│   ├── starship/              #   ~/.config/starship.toml
│   ├── bat/                   #   ~/.config/bat/
│   ├── zed/                   #   ~/.config/zed/
│   ├── git/                   #   ~/.gitconfig, ~/.gitignore_global
│   ├── gnupg/                 #   ~/.gnupg/
│   ├── scripts/               #   ~/.local/bin/
│   └── ...                    #   (i3, picom, polybar, gtk, etc.)
├── ansible/                   # System automation
│   ├── roles/                 #   Modular setup roles
│   │   ├── common/            #     Base system packages
│   │   ├── docker/            #     Docker engine (distro-specific)
│   │   ├── flatpak/           #     Flatpak runtime
│   │   ├── fonts/             #     System fonts
│   │   ├── ghostty/           #     Terminal emulator (distro-specific)
│   │   ├── fish/              #     Fish shell + set as default
│   │   ├── tmux/              #     Tmux + plugin manager
│   │   ├── mise/              #     Install mise + run mise install
│   │   ├── stow/              #     Deploy dotfiles via stow
│   │   └── cleanup/           #     Remove orphaned packages
│   ├── pre_tasks/             #   Pre-setup tasks
│   ├── group_vars/            #   Variable configurations
│   ├── inventory/             #   Host inventory
│   ├── configure_system.yml   #   System setup playbook
│   ├── clean_up_system.yml    #   Cleanup playbook
│   ├── main.yml               #   Master playbook
│   └── ansible.cfg            #   Ansible config
├── bin/
│   └── dotfiles               # Bootstrap script
├── stow.sh                    # Helper to stow/unstow all packages
├── Taskfile.yml               # Task runner
└── Dockerfile                 # Test environment

Each stow package mirrors the home directory structure. For example:

dots/nvim/.config/nvim/init.lua  -->  ~/.config/nvim/init.lua
dots/git/.gitconfig              -->  ~/.gitconfig
dots/mise/.config/mise/config.toml --> ~/.config/mise/config.toml
dots/scripts/.local/bin/foo      -->  ~/.local/bin/foo

Architecture: What goes where?

Stow - dotfiles and configuration

Any user-facing config file: shell, editor, git, tmux, terminal, mise tool list. If it lives under ~/.config/ or ~/, it belongs in dots/.

Ansible - system-level setup

Anything that needs sudo, is OS-specific, or involves system services:

• Base system packages (git, curl, python, htop, etc.)
• Docker installation and service enablement
• Flatpak runtime
• System fonts
• Terminal emulators with distro-specific install flows (Ghostty)
• Setting the default shell (Fish)
• Tmux package + plugin manager bootstrap
• Installing the mise binary itself

mise - developer tools and runtimes

Anything that is part of the development environment and should behave the same on Arch, Fedora, and Ubuntu:

• Language runtimes: Go, Node, Python, Rust, Bun
• CLI tools: neovim, ripgrep, fd, bat, fzf, eza, lazygit, starship, zoxide
• Go-based tools: air, goose, sesh, cobra-cli, delve
• Linters: golangci-lint, sqlc
• Infrastructure: terraform, uv

Decision rule: If it is part of the machine or OS → Ansible. If it is part of your development environment → mise.

Adding a new developer tool

# 1. Add to mise config
vim dots/mise/.config/mise/config.toml
# Add: "aqua:owner/repo" = "latest"

# 2. Install it
mise install

# 3. (Optional) If it has a config file, create a stow package
mkdir -p dots/toolname/.config/toolname
# Add config files, then: stow -d dots -t ~ toolname

Adding a new system package

Add it to ansible/roles/common/vars/<distro>.yml or create a new Ansible role if it needs distro-specific setup (repos, services, etc.).

Usage

Stow (dotfiles only)

# deploy all dotfiles
./stow.sh

# deploy a single package
stow -d dots -t ~ nvim

# remove symlinks
./stow.sh unstow

# re-deploy (unstow + stow)
./stow.sh restow

Ansible (system setup)

# run locally (via Taskfile)
task local

# run on remote homelabs
task ubuntu_homelabs

Update ansible/inventory/hosts.yml with your hosts and ansible/group_vars/ with your configuration.

---
all:
  children:
    ubuntu_homelabs:
      hosts:
        # <place_your_hosts_here>

    local:
      hosts:
        localhost:
          ansible_connection: local

For remote hosts, set up SSH keys and update ansible/ansible.cfg:

[defaults]
inventory = inventory/hosts.yml
private_key_file = <place_ssh_key_path_here>
roles_path = roles

Taskfile commands

Command	Description
task stow	Deploy all dotfiles via stow
task unstow	Remove all dotfile symlinks
task restow	Re-deploy all dotfiles
task mise	Install all developer tools via mise
task local	Run Ansible locally (your machine)
task ubuntu_homelabs	Run Ansible on Ubuntu homelab machines
task docker_build	Build the dotfiles Docker image
task docker_run	Run the dotfiles Docker container
task docker_build_and_run	Build and run the Docker container

Note

To test without installing anything on your system, run task docker_build_and_run.

Bootstrap script

bash dotfiles

This will install Ansible, clone the repo, and run the full playbook. Logs are stored in ~/.dotfiles.log.

First Run

On first run, ~/.dotfiles_first_run_check is created. The script will recommend a reboot to apply all changes.

License

Apache License, Version 2.0