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.

Best of both worlds: Stow for dotfiles, Ansible for system setup.

• Stow manages all configuration files (dotfiles). Adding a new tool is as simple as creating a directory and running stow.
• Ansible handles system-level setup: installing packages, configuring services, setting up development environments.

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)
│   ├── 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/
│   ├── kdenlive/              #   ~/.local/share/kdenlive/layouts/
│   ├── scripts/               #   ~/.local/bin/
│   └── ...                    #   (i3, picom, polybar, gtk, etc.)
├── ansible/                   # System automation
│   ├── roles/                 #   Modular setup roles
│   ├── 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/scripts/.local/bin/foo      -->  ~/.local/bin/foo

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

Kdenlive layouts

Only the custom editing layouts are tracked (Custom, Premiere, Vertical). They are plain JSON with no absolute paths, so they move between machines and install methods unchanged. Settings (kdenliverc) are deliberately not tracked — Kdenlive rewrites that file on nearly every exit and hardcodes install-specific binary paths in its [env] group.

stow kdenlive puts them at ~/.local/share/kdenlive/layouts, which is where a native build already reads from. Flatpak and macOS read from their own sandboxed locations, so they need a one-time symlink back to it.

Install	Layout directory	Setup
Native Linux	~/.local/share/kdenlive/layouts	stow only
Flatpak	~/.var/app/org.kde.kdenlive/data/kdenlive/layouts	stow + kdenlive-layouts link
macOS	~/Library/Application Support/kdenlive/layouts	stow + kdenlive-layouts link

Native Linux (dnf, pacman, apt) — nothing beyond the usual stow:

sudo dnf install kdenlive
stow -d dots -t ~ kdenlive      # already done by the ansible bootstrap

Flatpak or macOS — one extra command, once per machine:

flatpak install flathub org.kde.kdenlive   # or: brew install --cask kdenlive
kdenlive                                   # launch once so it creates its data dir
kdenlive-layouts link

Order does not matter — stow may run before Kdenlive is even installed.

Managing tracked layouts

kdenlive-layouts status   # which layouts are tracked
kdenlive-layouts pull     # adopt newly saved layouts into the repo

Editing an existing layout writes straight through its symlink into this repo, so it is tracked with no extra step. Only a layout saved under a brand new name lands outside the repo — kdenlive-layouts pull adopts it and re-stows.

Note

kdenlive is in stow_no_folding_packages, so stow creates real directories and symlinks the layout files individually. Without --no-folding, stow would collapse ~/.local/share/kdenlive into one symlink pointing at this repo, and Kdenlive's own .backup/, titles/ and library/ state would be written inside the dotfiles.

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