Documentation

🏠 Home

🏠 HorneroConfig - Comprehensive Dotfiles Framework

Docs | Changelog | Contributing

You might be here looking for (Linux) rice reference or to (full?) replicate my personal configuration of my favorite Window Managers and several apps as well. ⛄

HorneroConfig is your artisanal toolkit for crafting the perfect digital workspace. Named after the industrious hornero bird, renowned for its skillful nest-building, our framework empowers you to construct a robust, functional, and personalized computing environment.

Perfectly suited for a wide array of Desktop Environments and Window Managers, HorneroConfig thrives across different platforms including GitHub Codespaces, Gitpod, VS Code Remote - Containers, or even Linux distributions that are not Arch Linux.

Backed by the versatile Chezmoi, HorneroConfig stands out as a dotfiles manager that adapts flexibly to your needs, streamlining machine setup and ensuring consistency across devices. Embrace the spirit of the hornero, and let HorneroConfig transform your configurations into a harmonious blend of elegance and efficiency.

Most were written from scratch. Some details:

  • Window Manager 🍱 i3 and/or Openbox and/or XFCE!
  • Panel 🌸 Polybar which is a fast and easy-to-use status bar!
  • Application Launcher 🚀 Rofi which is blazing fast!
  • Desktop Notification 🌿 Dunst which is minimalist!
  • Terminal Emulator 🐾 Kitty The fast, feature-rich, GPU based terminal emulator!
  • Shell 🐚 Zsh with several post-installation tweaks!
  • Compositor 🍧 Picom for that perfection topping with Animations!
  • File Manager 🃏 Thunar with a customized side pane!
  • Widgets 🎨 Eww with 2 different pre-backed widgets!
  • and many more!

💥 Dots Scripts Utility

💥 Dots Scripts Utility Guide

As part of this dotfiles installation, we provide a curated collection of utility scripts that help automate and enhance your desktop experience. These scripts handle everything from brightness control to network checks, and they’re neatly organized under a single command: dots.

[!TIP] All scripts are fully customizable. You can modify them, add your own, or extend existing ones — and manage them with chezmoi just like any other part of your dotfiles.

🚀 What is dots?

dots is a wrapper utility that exposes various helpful scripts for configuring modules and interacting with your system.

You can use it directly from the terminal to:

  • Run scripts individually
  • Discover available helpers
  • Simplify your workflow

📦 Usage

dots --help     # Show help menu
dots --list     # List all available scripts
dots <script>   # Run a specific script (with optional flags)

🔍 Pro Tip: You can use chezmoi edit ~/.local/bin/dots to customize the wrapper script if needed.

📜 Available Scripts

📝 This list may evolve. To check the current list on your system, run: dots --list

  • brightness – Adjust screen brightness via xbacklight, brightnessctl, blight, or xrandr
  • check-network – Check if you’re connected to the internet
  • checkupdates – Query available package updates
  • feh-blur – Blur your wallpaper background with feh
  • git-notify – Send a notification after a Git commit
  • microphone – Mute/unmute or control mic levels
  • monitor – Display current monitor name
  • night-mode – Toggle night mode for low light environments
  • openweathermap-detailed – Show detailed weather info from OpenWeatherMap
  • popup-calendar – Display a calendar in a popup window
  • rofi-bluetooth – Manage Bluetooth devices using a Rofi menu
  • rofi-randr – Change screen resolution using a Rofi menu
  • rofi-run – Launch applications using a Rofi menu
  • rofi-xrandr – Extended screen resolution manager using Rofi and charts
  • screenshooter – Take screenshots or region captures
  • spotify – Display current song info from Spotify
  • sysupdate – Run a full system update
  • toggle – Toggle the state of specific apps or modules (e.g., Polybar menus)
  • updates – Check for software updates
  • weather – Display current weather summary

🧠 Customizing Scripts

All scripts can be found in your dotfiles repo (usually under ~/.local/bin/). To customize:

chezmoi edit ~/.local/bin/<script-name>
chezmoi apply

You can also add your own scripts and link them via the dots interface for quick access.

🆘 Need Help?

Use the dots utility to take your workflow to the next level. Automate, simplify, and enjoy the full power of your environment! ⚡

🎨 Customization

🎨 Dotfiles Customization Guide

This repository is designed to be a starting point for your personalized dotfiles setup. You’re encouraged to fork it, adapt it to your needs, and maintain your own GitHub repository with your custom configurations.

[!TIP] The dotfiles use Chezmoi to manage, edit, and apply configuration changes across multiple machines — securely and efficiently.

🛠️ Getting Started with Customization

1. Fork This Repository

Create your own version of the dotfiles:

git clone https://github.com/<your-username>/dotfiles.git ~/.dotfiles

2. Initialize Chezmoi

[!IMPORTANT] This dotfiles setup includes references to my personal LastPass vault for storing sensitive information (like tokens or secrets).
If you plan to use or adapt these configs, make sure to replace or remove any references to LastPass and configure your own preferred secret management method — such as Bitwarden, 1Password, pass, gopass, or chezmoi's built-in encrypted secrets.
Double-check any scripts or encrypted templates (*.tmpl) before applying changes.

Link your forked dotfiles directory with chezmoi:

chezmoi init --source ~/.dotfiles

3. Edit Your Configurations

Use chezmoi’s built-in editing command:

chezmoi edit --source ~/.dotfiles

Make the changes that suit your preferences:

  • Theme and style adjustments
  • New keybindings
  • Custom scripts
  • Tool settings and plugins

4. Apply Your Changes

Once you're ready:

chezmoi apply --source ~/.dotfiles

All changes will be synced to your system.

📁 What You Can Customize

  • 🪟 Window manager settings (i3, Openbox, XFCE4)
  • 💻 Terminal experience (Zsh, Kitty)
  • 🎨 Theme and color schemes (Rofi, Polybar, Pywal)
  • 🛠️ Utility scripts (dots) and workflow helpers
  • 🔒 Security tools and system behaviors

[!TIP] Use chezmoi diff to preview your changes before applying.

🌍 Multi-Machine Consistency

One of the biggest advantages of using Chezmoi is portable configuration. You can sync your setup across multiple machines using a private or public GitHub repository.

Just run:

chezmoi init git@github.com:<your-username>/dotfiles.git
chezmoi apply

And your personalized setup will be ready!

🆘 Need Help?

Go ahead — personalize everything. Make your desktop, terminal, and tooling truly yours! 🚀

🪟 Window Managers

🪟 Window Managers Configuration Guide

This guide provides an overview of how to customize the supported window managers in this dotfiles setup: i3, Openbox, and XFCE4.

[!TIP] Everything is fully customizable — from layout and keybindings to appearance and startup behavior. All configurations are version-controlled using chezmoi, making it easy to manage and sync.

🧱 General Customization Workflow

Regardless of the window manager, the general process is:

  1. Locate the config directory
  2. Edit files with chezmoi edit
  3. Apply changes with chezmoi apply
  4. Restart your WM or re-source configurations (if applicable)

🔲 i3 Window Manager

📁 Config Path: ~/.config/i3

The i3 configuration controls:

  • Keybindings
  • Workspace layout
  • Application launching
  • Status bar integration (e.g., Polybar)

To edit:

chezmoi edit ~/.config/i3/config
chezmoi apply

For more info, check the i3 customization documentation.

⚫ Openbox Window Manager

📁 Config Path: ~/.config/openbox

Openbox is a lightweight and highly customizable WM. You can tweak:

  • Window behavior and focus model
  • Desktop menus
  • Keybindings
  • Autostart applications

To edit configs:

chezmoi edit ~/.config/openbox/rc.xml
chezmoi apply

GUI alternative: Use obconf for quick edits to appearance and themes.

Explore more in the Openbox customization documentation.

🖥️ XFCE4 Desktop Environment

📁 Config Path: ~/.config/xfce4

XFCE4 is a full-featured desktop environment. Customizations here are global and apply across all your installed WMs.

Use the built-in Settings Manager:

xfce4-settings-manager

From there, configure:

  • Panels
  • Keybindings
  • Appearance
  • Power management
  • Preferred apps

You can also edit config files manually via chezmoi:

chezmoi edit ~/.config/xfce4 --source ~/.dotfiles
chezmoi apply

More details in the XFCE4 customization documentation.

🔧 Pro Tips

  • Add WM-specific autostart scripts or shared components
  • Mix and match (e.g., run Openbox with Polybar and Rofi)
  • Use chezmoi diff to preview config changes

🆘 Need Help?

If you run into issues or want to go deeper:

Customizing your window manager is one of the best ways to boost your productivity and tailor your desktop to your style — make it yours! 🎨

XFCE 4

🖥️ XFCE4 Configuration Guide

XFCE4 is a versatile, lightweight, and fully customizable desktop environment. It comes with a set of default configurations and strikes a great balance between performance and functionality. With the dotfiles installation, all your XFCE4 customizations are versioned and managed through chezmoi.

[!TIP] Everything in this setup is customizable — from themes and panels to keyboard shortcuts and power settings. You can use the Settings Manager or modify files directly.

🗂️ Configuration Files Location

Your XFCE4 configuration files are stored at:

~/.config/xfce4

These files are backed by XFCE4 components and apply globally across all the installed dotfiles and any window manager you use.

To make edits via chezmoi:

chezmoi edit ~/.config/xfce4 --source ~/.dotfiles

Apply your changes with:

chezmoi apply

[!TIP] Use chezmoi diff to preview changes before applying.

🌍 Global Configurations

All changes to XFCE4 will reflect globally across any window manager integrated in your dotfiles setup (such as Openbox or i3). This allows for a consistent and seamless experience across sessions.

🛠️ Using XFCE4 Settings Manager

You can visually manage most XFCE4 settings through the built-in XFCE4 Settings Manager (xfce4-settings-manager).

How to Launch

  1. Open the application menu (click the icon in the panel or press the Super key)
  2. Search for "Settings Manager" and click to open

Once opened, you'll see options like:

  • Keyboard shortcuts
  • Mouse and touchpad settings
  • Default applications (browser, terminal, file manager, etc.)
  • Power manager settings
  • Appearance (themes, icons, fonts)

Any changes here are written to the configuration files managed by chezmoi and apply globally to all dotfiles.

🔧 What You Can Customize

  • Panel layout and plugins
  • Autostart applications
  • Desktop background and display settings
  • Keybindings and workspace navigation
  • Compositor settings (like transparency and shadows)

Make changes either through the GUI or directly by editing files in ~/.config/xfce4.

[!TIP] Don’t forget to apply changes with chezmoi apply.

🧪 Tips & Tricks

  • Use picom for smooth compositing and transparency
  • Combine XFCE4 with tools like Polybar, Rofi, and Zsh for a more powerful environment
  • Replace xfce4-terminal with kitty or alacritty for improved terminal performance

🆘 Need Help?

XFCE4 offers the stability of a traditional desktop with the flexibility of modern customization. Explore, tweak, and make it your own! 🎨

i3 WM

🧱 i3 Window Manager Guide

i3 is a tiling window manager built to provide an efficient and highly customizable user experience. It allows you to manage your windows using simple keyboard shortcuts and scripting tools.

[!TIP] The i3 setup in this dotfiles project is fully configurable. You can personalize layouts, autostart programs, keybindings, and integrations with other tools like Polybar, Rofi, or EWW.

📁 Configuration Files Location

All i3-related configurations live in:

~/.config/i3

To edit using chezmoi:

chezmoi edit ~/.config/i3 --source ~/.dotfiles

Apply changes:

chezmoi apply

After editing, restart i3 (Mod+Shift+r) to reload the configuration.

📖 Official documentation: i3 User Guide

🚀 Autostart Applications

Autostart programs are defined in:

~/.config/i3/autostart.sh

This script runs when the i3 session starts. You can add anything here:

picom --experimental-backends &
feh --bg-scale ~/wallpapers/mywall.jpg &

Make sure the script is executable:

chmod +x ~/.config/i3/autostart.sh

⌨️ i3 Keybindings

We’ve predefined a set of intuitive keybindings in your i3/config file to help you get productive fast. You can modify or extend them as needed.

🔑 Default Keybindings

Key Action
$Mod+Shift+q Kill the current window
Mod1+F1 Launch Rofi using dots rofi-run -r
$Mod+d Launch EWW dashboard (~/.config/eww/dashboard/launch.sh)
$Mod+x Launch EWW power menu (~/.config/eww/powermenu/launch.sh)
$Mod+Ctrl+p Toggle Polybar menus (dots toggle -p -t &)
$Mod+w Launch default browser (exo-open --launch WebBrowser)
$Mod+f Launch file manager (exo-open --launch FileManager)
$Mod+t or $Mod+Return Launch terminal (exo-open --launch TerminalEmulator)
XF86MonBrightnessUp Brightness +10% (dots brightness "*" + 0.1)
XF86MonBrightnessDown Brightness -10% (dots brightness "*" - 0.1)
Shift+XF86MonBrightnessUp Brightness +1% (dots brightness "*" + 0.01)
Shift+XF86MonBrightnessDown Brightness -1% (dots brightness "*" - 0.01)
Print Screenshot tool (dots screenshooter)
Shift+Print Screenshot region (dots screenshooter -r)
XF86AudioPlay Play/Pause music (playerctl play-pause)
XF86AudioNext Next track (playerctl next)
XF86AudioPrev Previous track (playerctl previous)
XF86AudioStop Stop music (playerctl stop)
XF86AudioMute Toggle mute (pamixer -t)
XF86AudioRaiseVolume Volume up +1% (pamixer -i 1)
XF86AudioLowerVolume Volume down -1% (pamixer -d 1)

🧠 Customization Tips

  • Mix i3 with Polybar, Rofi, EWW, or Picom for a complete and modern setup
  • Use workspace-specific rules and gaps for better layout control
  • Define window-specific behavior (e.g., floating, no border)

🧪 Experiment with changes in a testing environment before applying them to your main config

🆘 Need Help?

Enjoy the power and flexibility of i3, and build your ideal window management experience! 💻✨

Openbox

🪟 Openbox Configuration Guide

Openbox is a lightweight and highly configurable window manager that provides a simple yet powerful environment for managing windows in your desktop. With its flexibility and extensive customization options, Openbox allows you to create a personalized and efficient workflow.

[!TIP] Everything in this setup is fully customizable. Whether it's the appearance, keybindings, or behavior — you have full control. All configuration files live in your dotfiles repo, versioned with chezmoi, and changes can be applied with chezmoi apply.

🗂️ Configuration Files Location

Your Openbox configuration files are located at:

~/.config/openbox

These files are managed via chezmoi. To edit them:

chezmoi edit ~/.config/openbox --source ~/.dotfiles

After editing, apply your changes with:

chezmoi apply

And restart Openbox for the modifications to take effect.

🔧 What You Can Customize

  • Window behavior (e.g., focus models, stacking order)
  • Keybindings (move, resize, switch windows, custom shortcuts)
  • Menus (right-click desktop menus, application launchers)
  • Autostart applications (programs that run when Openbox starts)
  • Appearance and theming

📂 Key Configuration Files

  • rc.xml: Main configuration file for keybindings and window behavior
  • menu.xml: Right-click desktop menu definition
  • autostart: List of applications to run on Openbox startup

[!TIP] Use chezmoi diff to preview changes before applying.

🖼️ Graphical Configuration with obconf

To simplify configuration, you can use obconf, a GUI configuration tool for Openbox.

If it's available in your package manager, install it:

# Example for Arch Linux
sudo pacman -S obconf

Then launch it:

obconf

You can adjust:

  • Themes and styles
  • Window decorations
  • Mouse behavior
  • Desktops and workspaces

✨ Great for quick changes without editing XML files.

🧩 Integration & Tips

  • Use in combination with Polybar, Rofi, and Zsh for a full personalized desktop experience
  • You can dynamically generate menus or autostart entries via scripts
  • Combine with tools like xrandr, feh, or picom for wallpapers, transparency, and compositor support

🆘 Need Help?

If you get stuck or want to learn more:

Unleash the power of Openbox and create a unique desktop environment that reflects your style and optimizes your daily tasks!

Kitty Terminal

🐱 Kitty Terminal Emulator Guide

Kitty is a modern, GPU-accelerated terminal emulator built for speed, flexibility, and customization. It’s ideal for developers, power users, and anyone who wants a fast, scriptable terminal experience.

[!TIP] Like everything in this setup, Kitty is fully customizable. You can tweak appearance, behavior, keybindings, and even integrate with your theme manager.

🚀 Why Use Kitty?

  • ⚡ GPU acceleration for smooth rendering
  • 🧩 Layouts and tab support
  • 🎨 Rich styling with font ligatures and emoji
  • 📜 Scriptable with shell commands
  • 📺 Inline graphics and image display support

⚙️ Configuration Basics

Kitty's configuration file is located at:

~/.config/kitty/kitty.conf

To edit it with chezmoi:

chezmoi edit ~/.config/kitty/kitty.conf
chezmoi apply

This file controls appearance, behavior, fonts, shortcuts, and more.

🎨 Installing and Applying Themes

Kitty supports full theme customization using its config system.

Using kitty-themes

We recommend using kitty-themes for easier management of community-curated themes.

Installation

git clone https://github.com/dexpota/kitty-themes ~/.config/kitty/themes

To list and apply a theme:

cd ~/.config/kitty/themes
./theme_launcher.sh  # Follow the prompts

This tool automatically updates your Kitty config with the selected theme.

🧠 Tips for Customizing Kitty

  • Use Nerd Fonts or JetBrainsMono for ligatures and icon support
  • Bind shortcuts to control tabs or launch commands
  • Use background_opacity for transparency
  • Customize scrollback, padding, and cursor style

Example snippet:

font_family      Hack Nerd Font Mono
font_size        11
background_opacity 0.95
enable_audio_bell no

📦 Bonus: Integrate with Pywal

Use pywal to generate a dynamic color scheme based on your wallpaper, and source the kitty.conf colors dynamically.

wal -i path/to/wallpaper.jpg

Kitty will use the updated colors from your ~/.cache/wal/colors-kitty.conf file.

🆘 Need Help?

Kitty gives you the performance of a modern terminal with the aesthetic and control of a true power tool. Make it yours! 🐱💻

Network Manager

🌐 Network Manager Guide

This section provides guidance for managing and configuring your network setup using NetworkManager, with custom dotfiles support.

[!TIP] Like everything else in this setup, the Network Manager integration is fully customizable. You can configure connections, UI tools, and even define shortcuts or scripts — all managed through your dotfiles and chezmoi.

⚙️ Tools You Can Use

Depending on your preference, you can use either graphical or terminal-based tools for managing networks:

1. nmtui – TUI interface (Text-based User Interface)

nmtui

Use this for:

  • Activating or deactivating connections
  • Connecting to Wi-Fi
  • Setting static IP addresses

2. nmcli – Command-line Interface

nmcli device wifi list
nmcli device wifi connect <SSID> password <password>

Use this for scripting, automating, or managing networks programmatically.

3. network-manager-applet – GUI tray icon

If you're running a system tray (e.g., via Polybar or XFCE), you can use the applet to manage Wi-Fi and VPNs.

Install:

sudo pacman -S network-manager-applet  # Arch-based

📁 Dotfiles Integration

While network configurations aren't typically stored directly in the dotfiles, you can:

  • Create helper scripts to automate Wi-Fi/VPN switching
  • Manage your tray applet visibility and behavior
  • Bind hotkeys for toggling Wi-Fi, VPN, or Airplane Mode

You can version any helper script or autostart command using chezmoi:

chezmoi edit ~/.config/autostart/network-helper.sh

✨ Example: Quick Connect Script

Here’s an example nmcli script that you can store in ~/.local/bin/connect-home-wifi.sh:

#!/bin/bash
nmcli device wifi connect "HomeWiFi" password "yourpassword"

Make it executable:

chmod +x ~/.local/bin/connect-home-wifi.sh

Add it to your chezmoi config or call it from a keybinding.

🧪 Debugging Network Issues

Useful nmcli commands:

nmcli general status
nmcli device
nmcli connection show
journalctl -u NetworkManager.service

🆘 Need Help?

Take control of your network configuration with tools that match your workflow — whether it's terminal, GUI, or automation! 📡

Polybar

🎨 Polybar Configuration Guide

Polybar is a highly customizable status bar that provides a sleek and elegant way to display system information such as date, CPU, memory, and more. It’s modular, lightweight, and visually beautiful.

[!TIP] Everything in this setup is fully customizable. Whether it's modules, colors, font, spacing, or interaction, you have total control. All configuration files are versioned in your dotfiles using chezmoi.

📁 Configuration Files Location

Your Polybar configuration is stored in:

~/.config/polybar

To edit it:

chezmoi edit ~/.config/polybar --source ~/.dotfiles

Apply changes with:

chezmoi apply

[!TIP] Run polybar-msg cmd restart to reload Polybar without restarting your session.

🔧 What You Can Customize

  • Bars: Define multiple bars for different monitors or purposes
  • Modules: Choose what system info to display (CPU, memory, network, etc.)
  • Fonts & Colors: Set font family, size, and colors (supports Nerd Fonts!)
  • Spacing & Alignment: Adjust padding, margins, and alignment
  • Behavior: Define click actions, scroll behavior, or auto-hide logic

🗂️ Main Files

  • config.ini: Main config file defining bars and module layout
  • modules/: Folder containing reusable and custom module logic
  • launch.sh: Custom launch script for initializing Polybar

📦 Default Modules Available

Polybar supports a variety of built-in and custom modules. Some examples:

  • date – current date/time
  • cpu – CPU usage
  • memory – RAM usage
  • battery – battery status
  • network – current IP, Wi-Fi, and signal
  • spotify – current playing track
  • i3 – workspace info for i3 users
  • custom/ – your own shell scripts or output

Check the documentation we have for each module in the sidebar!

🎨 Visual Styling Tips

  • Use pywal to dynamically theme your bar based on wallpaper
  • Integrate with icon fonts like Material Design or Nerd Fonts for better visuals
  • Adjust background transparency with a compositor like picom

🧪 Testing Your Setup

Make changes incrementally and restart only the bar:

polybar-msg cmd restart

If something crashes, run:

polybar your-bar-name -r

To test an individual bar defined in your config.ini

🆘 Need Help?

Design your own status bar and make your desktop truly yours. Polybar gives you the power — go wild! 🚀

Zsh Shell

🌀 Zsh Configuration Guide

Zsh (Z Shell) is a powerful, interactive shell that offers advanced features, extensive customization, and a vibrant ecosystem of plugins and themes.

[!TIP] Everything in this setup is fully customizable. From themes, prompts, plugins, to aliases and functions — you’re in control. All configuration lives in your dotfiles and is managed through chezmoi.

⚙️ Configuration Files Location

Zsh is configured using a modular structure inside:

~/.zsh/config.d/

Every .zsh file inside this folder is automatically sourced on shell startup.

To edit files using chezmoi:

chezmoi edit ~/.zsh/config.d/yourfile.zsh --source ~/.dotfiles

Apply changes with:

chezmoi apply

[!TIP] Use separate files for aliases, plugins, and theme settings for better organization.

🔧 What You Can Customize

  • Prompt themes (e.g., Powerlevel10k)
  • Plugin managers (e.g., Antigen, Oh My Zsh)
  • Aliases and shell functions
  • Autocompletion and syntax highlighting
  • Environment variables

🎨 Prompt Themes

Powerlevel10k

To use Powerlevel10k:

  1. Install the theme
  2. Create a config file:
chezmoi edit ~/.zsh/config.d/p10k.zsh
source /usr/share/zsh-theme-powerlevel10k/powerlevel10k.zsh-theme
[ ! -f ~/.p10k.zsh ] || source ~/.p10k.zsh

Run p10k configure to customize your prompt interactively.

🔌 Plugin Managers

Antigen

Antigen allows you to load and manage plugins easily:

curl -L git.io/antigen > ~/.antigen.zsh
# ~/.zsh/config.d/antigen.zsh
source "$HOME/.antigen.zsh"
antigen apply

Oh My Zsh

Install with:

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Configure in:

# ~/.zsh/config.d/oh-my-zsh.zsh
export ZSH="/your/oh-my-zsh/path"
source "$ZSH/oh-my-zsh.sh"

📁 Structure and Recommendations

We recommend keeping your customizations modular:

  • aliases.zsh: command shortcuts
  • functions.zsh: reusable shell functions
  • theme.zsh: your theme settings
  • plugins.zsh: plugin manager logic

This keeps your configuration clean and easy to maintain.

🧪 Testing Changes

After editing your configuration:

source ~/.zshrc

Or simply open a new terminal tab/session.

[!TIP] Use zsh -x to debug issues during shell startup.

🆘 Need Help?

Zsh is not just a shell — it’s a productivity tool. Customize it to reflect your style and workflow! ⚡

🛡️ Privacy and Security

🛡️ Security Guide

While these dotfiles are designed to provide a beautiful and personalized setup, privacy and security are just as important. This is an evolving journey — not a one-time setup — and we’re always open to suggestions.

[!TIP] You can tailor the security tools and settings to your preferences. All configurations can be automated or versioned using chezmoi where applicable.

🔒 Security Practices in Use

Here’s a list of tools and practices currently in place or under consideration:

✅ System Updates

  • Regular updates are essential.
  • I manually keep the system up-to-date using the package manager.
yay -Syyu  # [I use Arch, btw](https://wiki.archlinux.org/title/Arch_Linux)

[!TIP] Consider automating this process with a cron job or alias.

🛡️ Malware Scanning

  • ClamAV:
    • Run manual or scheduled scans
    • Keep virus database updated
sudo freshclam  # Update database
clamscan -r /home/youruser

🔥 Firewall

  • ufw: Simple firewall setup and management
sudo ufw enable
sudo ufw default deny incoming
sudo ufw allow out

🚫 IP Banning

  • fail2ban: Blocks IPs that show malicious behavior
sudo systemctl enable --now fail2ban

Check logs:

sudo fail2ban-client status

🔐 Password Management

If self-hosting or CLI usage is preferred, Bitwarden offers Bitwarden CLI.

🧬 Optional Hardening

  • Hardened Linux Kernel (optional):
    • A stricter kernel for additional protections
    • Great for advanced users but may break things unexpectedly

[!WARNING] Only recommended if you know your use cases won't be impacted.

🔎 Network & Port Scanning

  • nmap: Comprehensive network scanner
  • rustscan: Faster, modern alternative
sudo nmap -sS -p- 192.168.1.1
rustscan -a 192.168.1.1

Use for auditing your local network or spotting unknown open ports.

🧪 Tips for Staying Secure

  • Use strong, unique passwords + 2FA where possible
  • Don’t run random scripts without reading them first
  • Use aliases to simplify safe commands (e.g., update-all)
  • Consider using a VPN and encrypted DNS (like DoH or DoT)
  • Keep regular backups in case of compromise

🆘 Need Help?

Security is an ongoing practice — start with the basics, stay informed, and evolve over time 🔐

📁 Dots Backup Tool

This documentation is not ready yet. Please come back later or ask for help in the Discussions section!

⏏️ Dots Eject

🧨 Dots Eject Guide

While Chezmoi is a powerful and recommended tool for managing dotfiles across multiple systems, we understand that some users may prefer to maintain their own independent distribution.

[!TIP] This guide helps you eject from chezmoi and take full manual control of your dotfiles — useful for advanced users or custom workflows.

🚀 Why Use Chezmoi?

Chezmoi offers:

  • 🔁 Synchronization of dotfiles across machines
  • 🧼 Separation of source/config vs. applied state
  • 🔐 Secret management
  • 🔧 Easy templating and onboarding of new environments

But if you no longer wish to use chezmoi, you can safely eject.

📦 How to Eject from Chezmoi

Follow the official guide here: 👉 Migrate away from chezmoi

The process includes:

  1. Applying all changes to your home directory:

    chezmoi apply

  2. Copying the real files to a new git-tracked directory:

    mkdir ~/my-dotfiles
chezmoi managed --include=all | xargs -I {} cp --parents {} ~/my-dotfiles/
cd ~/my-dotfiles && git init

  3. Removing chezmoi from your workflow:

    sudo pacman -Rns chezmoi  # or appropriate command for your distro

Now you're managing your dotfiles fully manually or with your own tooling.

🧠 Things to Consider Before Ejecting

  • ✅ Are you managing secrets that chezmoi helps encrypt?
  • ✅ Do you still want templating, or are static files fine?
  • ✅ Do you want a clean separation between machine-specific and shared config?

If the answer is “no” or “you want full control,” ejecting is a valid next step.

🆘 Need Help?

Whether you stay with chezmoi or go fully manual, the goal is the same: dotfiles that reflect your ideal workflow. Choose the path that works best for you. 🛠️

🧪 Testing Environment

🧪 Dotfiles Testing Environment Guide

Whether you're looking to contribute to the Dotfiles project or simply want to preview how everything looks before applying it to your system — we've got you covered with dedicated testing environments.

[!TIP] The testing setup allows you to experiment safely without affecting your real configuration. It’s a perfect playground for customizing themes, scripts, and behaviors.

🚀 Why Use the Testing Environment?

  • 🧰 Preview your desktop layout and tool behavior
  • 🔧 Tweak configs and see changes instantly
  • 🤝 Contribute improvements with confidence
  • 🧼 Avoid breaking your daily setup during experimentation

📖 How to Get Started

To learn how to set up the test environments, check out the official Testing Docs.

These docs include:

  • Environment requirements
  • Setup steps (VM or container)
  • How to apply dotfiles without affecting your main system

🔁 What Can You Test?

You can try out:

  • 🪟 Window managers (Openbox, XFCE4, i3)
  • 🎨 Themes (Rofi, Polybar, Zsh prompt)
  • 🧩 Modules and utilities
  • 🧪 Custom scripts or aliases
  • 🛡️ Security configurations and defaults

🔄 Use this environment as a sandbox — test safely and iterate freely.

🧠 Tips for Effective Testing

  • Use a virtual machine or container for complete isolation
  • Snapshot your test environment before big changes
  • Commit working test configs to a feature branch before merging
  • Use chezmoi apply --dry-run to simulate changes before applying

🆘 Need Help?

Contributing or customizing just got easier. Jump into the testing environment, play around, and see how everything fits your workflow — worry-free!

Happy testing 🧪🎉

💯 Contributing

Thank you for considering contributing to Dotfiles! We appreciate your interest in improving the project. To ensure a smooth and collaborative contribution process, please review the following guidelines.

Communication

Before making any changes or submitting a pull request, we recommend discussing your proposed changes with the repository owners. This can be done through creating an issue, sending an email, or any other method of communication that suits you. Engaging in a discussion beforehand helps ensure that your contributions align with the project's goals and guidelines.

Please note that Dotfiles has a Code of Conduct that we expect all contributors to adhere to. Kindly follow the code of conduct in all your interactions within the project community.

Ways to Contribute

You can contribute to Dotfiles in various ways, including:

Pull Requests

To contribute through a pull request, please follow these steps:

  1. Fork the Dotfiles repository to your own GitHub account.
  2. Create a new branch for each feature or improvement you plan to work on.
  3. Submit a pull request from each feature branch to the master branch of the main repository.

It's essential to separate new features or improvements into separate feature branches and submit a pull request for each branch. This allows us to review and merge new contributions individually, ensuring better visibility and management of changes.

Code Guidelines

When writing code for Dotfiles, please adhere to the following guidelines:

  • Follow shell scripting best practices, such as those outlined in Google's Shell Style Guide.
  • Aim for POSIX compliance to ensure compatibility across different environments.
  • Use double quotes around variables ("${variable}") instead of bare variables ($variable).
  • Use UPPER_CASE for constants and global variables, and lower_case for other variables.
  • Utilize single square brackets ([ condition ]) for conditionals, such as in 'if' statements.
  • Write clean and readable code, emphasizing clarity and maintainability.
  • Add comments where necessary, especially to explain complex functions or provide context.
  • Clearly document the arguments that a function accepts (if any).
  • Use different error codes when exiting a script and provide explanations for them at the top of the file.
  • Include a copyright disclaimer below the shebang line and any other relevant copyright notices when creating new files or making significant changes.
  • Limit lines to a maximum of 80 characters for improved readability.
  • Name setup scripts as setup-<function> without file extensions.
  • Use the .sh extension for libraries and exclude the shebang line.
  • Scripts and libraries should not be executable, as permissions will be set during compilation.
  • Validate your code using a shell linter, such as shellcheck.
  • Test your code before submitting a pull request (unless it's a draft).
  • Provide detailed and informative commit messages that accurately describe the changes made.

Thank you for considering these guidelines when contributing to Dotfiles. Your efforts contribute to the project's quality and overall success. Happy coding!