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 🌿 Alacritty which is GPU accelerated!
  • Shell 🐚 Zsh with several post-installation tweaks!
  • Compositor 🍧 Picom fork by FT-Labs 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

In the dotfiles installation process, various scripts are added for configuring applications and modules. While these scripts are primarily used for module configuration, they can also be used independently. To simplify the management of these scripts, we provide the dots utility.

The dots utility provides a convenient way to manage and execute these scripts. You can explore their functionalities and customize them as needed.

Usage

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

Available Scripts

NOTE: The following list may not be exhaustive. You can always check the up-to-date list of scripts by running dots --list.

  • brightness: Control the screen brightness using various backends such as xbacklight, brightnessctl, blight, or xrandr.
  • check-network: Check if the network connection is up.
  • checkupdates: Check for updates.
  • feh-blur: Blur the background of the current window when using feh to set the wallpaper.
  • git-notify: Show a notification when a git commit is made.
  • microphone: Control the microphone settings.
  • monitor: Print the name of the current monitor.
  • night-mode: Toggle night mode.
  • openweathermap-detailed: Print detailed weather information.
  • popup-calendar: Show a calendar in a popup.
  • rofi-bluetooth: Show a rofi menu to manage Bluetooth devices.
  • rofi-randr: Show a rofi menu to manage the screen resolution.
  • rofi-run: Show a rofi menu to run commands.
  • rofi-xrandr: Show a rofi menu to manage the screen resolution with charts.
  • screenshooter: Take a screenshot.
  • spotify: Get information about the currently playing song in Spotify.
  • sysupdate: Update the system.
  • toggle: Toggle the state of specific applications.
  • updates: Check for updates.
  • weather: Print the current weather information.

Feel free to use these scripts to enhance your system configuration and workflow!

🎨 Customization

You can fork this repository and customize it to suit your preferences and workflow. You are encouraged to maintain a separate GitHub repository of configurations for your own dotfiles and keep this repository as a template!

We use Chezmoi to manage the dotfiles. Chezmoi is a sophisticated yet easy-to-use command-line tool that helps you manage your dotfiles across multiple machines. It is designed to be secure, flexible, and easy to use.

To customize the dotfiles, follow these steps:

  1. Run the command chezmoi init --source ~/.dotfiles to initialize Chezmoi.

  2. Run the command chezmoi edit --source ~/.dotfiles to open the dotfiles directory.

  3. Customize the dotfiles to suit your preferences and workflow.

  4. Run the command chezmoi apply --source ~/.dotfiles to apply the changes.

Feel free to customize and personalize your dotfiles to suit your preferences and workflow!

🪟 Window Manager

🖌️ You can customize the installed window managers, including i3, Openbox, and XFCE4, to suit your preferences and workflow. Here's how you can customize each of them:

i3 Window Manager

To customize i3, you can modify the configuration files located in the ~/.config/i3 directory. These files control various aspects of i3's behavior, such as keybindings, workspace layouts, and appearance. After making any changes, run the command chezmoi apply to update the i3 configuration.

For more detailed instructions and information about i3 customization, please refer to the i3 customization documentation.

Openbox Window Manager

For customizing Openbox, you can edit the configuration files located in the ~/.config/openbox directory. These files define the behavior, appearance, and keybindings for Openbox. Make your desired changes to these files, and then run command chezmoi apply --source ~/.dotfiles to apply the changes.

If you need additional guidance or want to explore more about Openbox customization, please visit the Openbox customization documentation.

XFCE4 Window Manager

XFCE4 customization is handled through the xfce4 tools included in the dotfiles installation. To customize XFCE4, use the xfce4 settings manager (xfce4-settings-manager). This utility allows you to modify various aspects of the XFCE4 desktop environment, including themes, appearance, panels, and more. Any customizations made through the xfce4 settings manager will be applied globally to all the installed dotfiles and affect all the window managers you have installed.

For more detailed instructions and tips on XFCE4 customization, please refer to the XFCE4 customization documentation.

🔧 Remember to run command chezmoi apply --source ~/.dotfiles after making any changes to the configuration files to ensure that the customizations are applied.

Feel free to customize each window manager according to your preferences, and if you have any further questions or need more specific guidance, please refer to the respective documentation for each window manager.

IMPORTANT: If you encounter any issues or need further assistance with customization, please refer to the dotfiles documentation or seek help from the dotfiles community.

XFCE 4

XFCE4 is a versatile and lightweight desktop environment that comes with a set of default configurations. In the dotfiles installation, XFCE4 configurations are located at ~/.config/xfce4. These configurations are backed by XFCE4 components, which means that any customization you apply to XFCE4 will be applied globally to all the installed dotfiles.

Remember to run chezmoi apply --source ~/.dotfiles after making any changes to the configuration files to ensure that the customizations are applied.

Global Configurations

The installed dotfiles are backed by some XFCE4 components, which means that any customization you apply to XFCE4 will be applied globally to all the installed dotfiles. This allows you to have consistent configurations across different window managers.

Using XFCE4 Settings Manager

To customize XFCE4 configurations, you can use the XFCE4 Settings Manager (xfce4-settings-manager). This utility provides a graphical interface for modifying various aspects of the XFCE4 desktop environment.

Here's how you can access the XFCE4 Settings Manager:

  1. Open the application menu by clicking on the menu icon in the panel or by pressing the Super key.
  2. Search for "Settings Manager" and click on it to open the manager.

The XFCE4 Settings Manager window will open, providing a range of options for customization.

In the XFCE4 Settings Manager, you can customize various settings, including:

  • Keyboard shortcuts
  • Mouse and touchpad settings
  • Default applications, such as the browser, terminal emulator, and file manager
  • Power manager settings
  • Appearance settings, and more

By making changes in the XFCE4 Settings Manager, you can modify the common configuration for all the installed dotfiles, ensuring a consistent experience across different window managers.

Customization Freedom

Feel free to explore the XFCE4 Settings Manager and tweak the configurations to suit your preferences. You have the flexibility to customize XFCE4 and make it align with your workflow and visual style.

Remember, any changes you make in the XFCE4 Settings Manager will be applied globally to all the installed dotfiles, providing a unified experience across your window managers.

In case you want to customize anything related to XFCE4 or any other tool in general, the dotfiles installation provides the flexibility to modify the configurations according to your needs.

📝 Note: If you encounter any issues or need further assistance with XFCE4 customization, please refer to the dotfiles documentation or seek help from the dotfiles community.

Enjoy customizing XFCE4 and make it your own!

i3 WM

The i3-wm configuration is located at ~/.config/i3. This file contains the actual configuration for i3-wm, and you have complete freedom to customize it according to your preferences.

To edit the i3-wm configuration, you need to run the following command:

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

Remember to apply your changes using chezmoi apply and restart i3-wm for the modifications to take effect.

To understand the different options available for customization, you can refer to the i3 User Guide, which provides detailed documentation on various aspects of the i3 window manager.

Autostart Applications

In the dotfiles installation, we have included a list of applications that are automatically started when the i3 session begins. You can find this list in the ~/.config/i3/autostart.sh file. Feel free to modify this file to add or remove applications based on your requirements.

i3 Keybindings

We have predefined some keybindings in the i3 configuration to enhance your workflow. These keybindings are designed to be intuitive and efficient. Here are some of the keybindings we have set:

Key Action
$Mod+Shift+q Kill the current window
Mod1+F1 Open the application launcher using the dots rofi-run -r command
$Mod+d Open the eww dashboard using the ~/.config/eww/dashboard/launch.sh command
$Mod+x Open the exit menu using the ~/.config/eww/powermenu/launch.sh command
$Mod+Control+p Open/close the polybar menus using the dots toggle -p -t & command
$Mod+w Open the default web browser using the exo-open --launch WebBrowser command
$Mod+f Open the default file manager using the exo-open --launch FileManager command
$Mod+t or $Mod+Return Open the default terminal emulator using the exo-open --launch TerminalEmulator command
XF86MonBrightnessUp Increase the brightness by 10% using the dots brightness "*" + 0.1 command
XF86MonBrightnessDown Decrease the brightness by 10% using the dots brightness "*" - 0.1 command
Shift+XF86MonBrightnessUp Increase the brightness by 1% using the dots brightness "*" + 0.01 command
Shift+XF86MonBrightnessDown Decrease the brightness by 1% using the dots brightness "*" - 0.01 command
Print Open the default screenshot tool using the dots screenshooter command
Shift+Print Take a screenshot of a region using the dots screenshooter -r command
XF86AudioPlay Play/pause the current song using the playerctl play-pause command
XF86AudioNext Play the next song using the playerctl next command
XF86AudioPrev Play the previous song using the playerctl previous command
XF86AudioStop Stop the current song using the playerctl stop command
XF86AudioMute Mute/unmute the current song using the pamixer -t command
XF86AudioRaiseVolume Increase the volume by 1% using the pamixer -i 1 command
XF86AudioLowerVolume Decrease the volume by 1% using the pamixer -d 1 command

These keybindings are designed to improve your productivity and streamline your interaction with i3. However, you are free to modify or add additional keybindings as per your preferences.

🔍 If you want more details or need further customization options, please refer to the i3 User Guide and explore the vast possibilities of customizing i3 according to your needs.

Enjoy the power and flexibility of i3, and personalize it to create your ideal window manager environment!

Openbox

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.

The openbox configuration files are located at ~/.config/openbox. This gives you the freedom to fully customize and fine-tune Openbox according to your preferences.

To edit the openbox configuration, you need to run the following command:

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

Remember to apply your changes using chezmoi apply and restart Openbox for the modifications to take effect.

Configuring Openbox

To simplify the configuration process, you can use obconf, a graphical configuration tool designed specifically for Openbox. obconf provides an intuitive interface that allows you to easily customize various aspects of Openbox, including window appearance, desktop settings, mouse behavior, and more.

If obconf is available in your package manager, you can install it using the appropriate installation command for your operating system. Once installed, you can launch obconf and explore the wide range of customization options it offers.

Using obconf, you can conveniently tweak and adjust Openbox without directly modifying the configuration files. This makes it easy to experiment, fine-tune your settings, and create a seamless desktop experience tailored to your workflow.

If obconf is not available in your package manager, don't worry! You can still configure Openbox by manually editing the configuration files located at ~/.config/openbox. These files provide detailed control over various aspects of Openbox's behavior, allowing you to customize window placement, keybindings, desktop menus, and much more.

Remember to save your configuration changes and restart Openbox for the modifications to take effect. This will ensure that your personalized Openbox setup is applied and ready to enhance your productivity and workflow.

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

Alacritty

Alacritty is a blazing-fast, GPU-accelerated terminal emulator that offers a highly customizable and efficient terminal experience. It is designed to be simple yet powerful, providing exceptional performance while consuming minimal system resources.

When you install the dotfiles for Alacritty, you gain access to a comprehensive collection of themes from the alacritty-theme repository. These themes are located in the directory ~/.config/alacritty/themes.

Switching Themes with alacritty-themes

To switch between themes, you can manually modify the Alacritty configuration files. However, we highly recommend using the convenient tool called alacritty-themes for a seamless and hassle-free theme management experience.

With alacritty-themes, you can easily browse, preview, and apply different themes to your Alacritty terminal emulator. The tool provides a user-friendly command-line interface that simplifies the process of selecting and configuring themes.

To use alacritty-themes, follow these steps:

  1. Install alacritty-themes by following the installation instructions provided in the alacritty-themes repository.

  2. Launch alacritty-themes by executing the command alacritty-themes in your terminal.

  3. Explore the available themes, preview them, and select the one that suits your preference.

  4. Once you have chosen a theme, alacritty-themes will automatically update your Alacritty configuration with the selected theme, providing you with an instant visual transformation of your terminal.

Here's a glimpse of how alacritty-themes works:

By using alacritty-themes, you can effortlessly personalize your Alacritty terminal with stunning visual styles, enhancing both the aesthetics and functionality of your command-line environment.

Experience the speed, flexibility, and beauty of Alacritty, combined with a rich collection of themes, to create a truly delightful and tailored terminal experience.

Network Manager

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

Polybar

🎨 Polybar is a highly customizable status bar that provides a sleek and elegant way to display system information, such as date and time, CPU usage, memory usage, and more. It offers a wide range of configuration options, allowing you to create a personalized and visually appealing status bar.

Why Polybar?

Polybar stands out as a popular choice for many users due to its flexibility, extensibility, and aesthetic appeal. Here are some reasons why we recommend using Polybar:

✨ Customization: Polybar offers extensive customization options, allowing you to fine-tune every aspect of your status bar. From colors and fonts to module placement and formatting, you have full control over the appearance and behavior of your bar.

🚀 Lightweight: Polybar is designed to be lightweight and efficient, ensuring minimal impact on system resources. It leverages XCB (X C-language Bindings) to provide a fast and responsive user interface.

🧩 Modularity: Polybar follows a modular approach, enabling you to add and configure various modules to display specific system information. With a wide range of available modules and the ability to create custom modules, you can tailor your status bar to meet your specific needs.

🌈 Visual Appeal: Polybar allows you to create visually stunning status bars that seamlessly integrate with your desktop environment. With support for icons, different font styles, and customizable module formatting, you can design a status bar that matches your aesthetic preferences.

Configuration Parameters

Polybar's configuration is highly parameterizable, allowing you to customize various aspects of your bar. To modify these parameters, you can edit the files running chezmoi edit ~/.config/polybar --source ~/.dotfiles.

Within this directory, you will find a wide amount of files that can be adjusted to create your unique Polybar setup. These parameters enable you to customize different bars, define module behavior, and leverage the provided tools and utilities to enhance your Polybar experience.

Explore the available parameters, experiment with different values, and fine-tune your Polybar configuration to create a status bar that reflects your style and provides the information you desire.

Customize your Polybar, unleash your creativity, and enjoy a beautifully designed and informative status bar that enhances your desktop workflow.

Zsh

💡 Introduction

Zsh, or Z Shell, is a powerful and feature-rich shell that provides an enhanced command-line experience. It offers a wide range of interactive features, extensive customization options, and advanced scripting capabilities. In our dotfiles setup, we have chosen to use Zsh as the default shell due to its numerous advantages over other shells like Bash or Fish.

🚀 Improved User Experience

Zsh provides advanced features that enhance productivity and convenience. With features like advanced tab completion, spelling correction, history search, and powerful globbing capabilities, working with the command line becomes easier and faster.

🔧 Customization Options

Zsh is highly customizable, allowing you to personalize your shell environment. You can define custom functions, aliases, and keybindings to streamline your workflow. Additionally, Zsh offers a wide range of prompt themes and plugins to enhance your shell experience, making it adaptable to your preferences and needs.

💡 Advanced Scripting Support

Zsh offers a powerful scripting language with additional features compared to other shells. It supports advanced control structures, associative arrays, and regular expressions, making it an excellent choice for scripting complex tasks. Zsh's scripting capabilities enable you to write efficient and robust scripts.

🔋 Extensive Plugin Ecosystem

Zsh has a vibrant community that has developed numerous plugins and extensions to extend its functionality. You can easily enhance your Zsh environment with plugins for syntax highlighting, auto-suggestions, Git integration, and more. These plugins greatly improve productivity and make working in the shell more enjoyable.

🔗 Seamless Compatibility

Zsh is fully compatible with most shell scripts written for Bash. You can run your existing Bash scripts without any modifications in Zsh, ensuring a smooth transition. Additionally, Zsh provides better handling of corner cases and edge scenarios, making it a reliable choice for shell scripting.

Customizing Zsh!

Any file in your ~/.zsh/config.d directory ending with .zsh will automatically be sourced when you open a shell. You can use this to add additional aliases, functions, and more.

Zsh + Antigen Antigen is a small set of functions that help you easily manage your shell (Zsh) plugins, called bundles. It is similar to bundles in a typical vim+pathogen setup. To add Antigen as your plugin manager, execute the following command to download the latest stable version of Antigen into your home directory (check the installation steps for more details): sh curl -L git.io/antigen > ~/.antigen.zsh Then, create the file ~/.zsh/config.d/antigen.zsh with the following content: sh source "${HOME}"/.antigen.zsh antigen apply This file will be automatically sourced.
Zsh + Power Level 10k You can use Power Level 10k as your Zsh theme by installing it and creating a custom file, e.g., ~/.zsh/config.d/p10k.zsh, with the following content: sh # Source Power Level 10k 💡 source /usr/share/zsh-theme-powerlevel10k/powerlevel10k.zsh-theme # 💡 # To customize prompt, run `p10k configure` or edit ~/.p10k.zsh. [ ! -f ~/.p10k.zsh ] || source ~/.p10k.zsh This file will be automatically sourced.
Zsh + Oh My Zsh To customize your dotfiles setup to use Oh My Zsh, you can follow these steps: 1. Install Oh My Zsh by running the following command in your terminal: shell sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" 2. Once Oh My Zsh is installed, you can create a custom file, e.g., ~/.zsh/config.d/oh-my-zsh.zsh, with the following content: shell # Load Oh My Zsh export ZSH="/your/oh-my-zsh/path" source "$ZSH/oh-my-zsh.sh" Make sure to replace /your/oh-my-zsh/path with the actual path to your Oh My Zsh installation directory. 3. Additionally, you can customize your Oh My Zsh configuration by creating or modifying the .zshrc file in your home directory. This file will be automatically sourced when you open a shell. 4. Restart your terminal or open a new shell session to apply the changes. Oh My Zsh should now be active, and your customizations will take effect. With these steps, you can easily integrate Oh My Zsh into your dotfiles setup and take advantage of its powerful features and community-driven plugins and themes. Feel free to explore the Oh My Zsh documentation and customize your shell experience to suit your needs and preferences. Happy customizing! ✨🚀

🛡️ Privacy and Security

Although I like making it look as nice as possible, these dotfiles also try to be private and secure. This is a journey, not a destination, and I am open to any input.

  • Manually keeping system up to date using the OS package manager. I use Arch, btw so I run yay -Syyu every day.
  • Malware scanning and database updating (clamav).
  • Firewall (ufw)
  • Ban IPs (fail2ban)
  • Using a Password Manager. I use LastPass, but I am considering switching to Bitwarden.
  • I could install the hardened Linux kernel, but that might be slightly pedantic...
  • Port scanning (nmap, rustscan)

📁 Dots Backup Tool

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

⏏️ Dots Eject

We encourage you to use Chezmoi as a tool to keep your dotfiles always updated and maintain a consistent configuration across your systems. However, we understand that there may be situations where you want to have your own independent distribution of dotfiles.

To eject from Chezmoi and create your own dotfiles distribution, you can follow the steps documented in the guide Migrate away from chezmoi.

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

🧪 Testing

If you're interested in contributing to the Dotfiles project or simply want to preview the setup before installing it on your own system, we have developed test environments that allow you to see how the changes will look and behave.

To learn more about setting up and using these test environments, please refer to the Testing Docs on the project's GitHub repository. The Testing Docs provide detailed instructions on how to get started with the test environments and explore the different configurations and features.

By utilizing the test environments, you can gain a better understanding of how Dotfiles works, experiment with different settings, and ensure a smooth experience before applying the changes to your own system.

We encourage you to take advantage of these test environments to make your contributions or explore the project. It's a great way to familiarize yourself with Dotfiles and ensure a seamless integration with your workflow.

Happy testing!