Dotfiles

README is a WIP

• Components
• XDG Base Directory
• Scripts
• Self-hosted

Personal configuration files used in a Void distribution. This collection of configs is very opinionated and tailors to a very cli-centric approach.

Managed with GNU Stow.

If you'd like to bootstrap my whole system configuration from a fresh install run up, else, if you'd only like to grab a config for a specific program, run stow ${dir}

It is advised to run up --dirs prior to using stow to avoid symlinking whole configuration or data directories such as .config or .local. For reference and to select the config folders you are interested in, see up

Note that some files which I consider sensitive are encrypted with git-crypt and defined in .gitattributes. If you have my GPG key passphrase, you can unlock them either with git-crypt unlock or git-crypt init in the project's root directory.

Components

• OS (Operating System) - Void

I enjoy Void's simplicity and mainly chose it because of its minimal base-system meta package and its minimalistic approach to what should a Linux distribution offer. I like the fact that they evaluate with great care the most minimal and appropriate solutions for many areas of the OS, for example, they chose runit as its init system over the complex systemd, which makes managing system services extremely trivial and allows for boot times of ~3 seconds.

Another reason why I opted for Void was wanting to build my own packages or at least try to understand how the build scripts work, as I previously used Arch Linux and due to its larger userbase and the AUR (Arch User Repository), almost any pacakge I found the need to install was already built. The fact that I had an AUR helper made me not read PKGBUILDs before installing any piece of software into my system and once I realised the security risks involved with it, I decided to jump ships. XBPS (X Binary Package System) - Void's package manager - is extremely fast too which also comes very handy when building custom packages through its utility xbps-src.

I currently maintain a fork of void-packages - XBPS official package repository - as, even though Void has more packages than the standard Arch repositories, package requests are very strictly qa'd, which means that some tools may be missing or due to licensing issues, they can't be redistributed. I must say that I find building a Void's build template much more cohesive than a PKGBUILD, as its syntax is much less syntactically flavoured and it includes many build_styles which makes building software extremely simple.

• Display server - X.Org Even though it is said to be abandonware, it's still a very stable display server.
• WM (Window Manager) - bspwm

I use BSPWM (Binary Space Partitioning Window Manager) because of the amount of customisability it provides by using a single binary bspc to control all its behaviour. The fact that I'm able to write shell scripts to tweak it to my liking is its killer feature and I also very much enjoy its default window representation as leaves of a binary tree. It also sticks to the UNIX philosophy, as the only things it provides is a window manager, no status bars or fancy notification panels. Most times I'm using my laptop plugged to an external monitor, so I have a custom script wm subscribe which listens to monitor events and rearranges desktops automatically according to the display(s) connected. I also like the fact that I can adjust window rules however I wish. For example, in my custom script term, in which I overlay an mpv window with a terminal window with the video info/comments, I'm able to set a sizing rule that inherits the window size of the current window as a one-off.

• Hotkey daemon: sxhkd
• Status bar: polybar

Built-in modules I currently use:

• battery
• bspwm to show BSPWM workspaces
• date with a click action for YAD to display a calendar popup.
• network
• text to display Powerline separators
• xkeyboard

I've also written the following script/module_name:

• alsa_toggle allows you to toggle the ALSA's Auto-Mute Mode (if your soundcard supports it) to be able to output audio through your device speakers when a cable jack is connected to it at the same time, for example.
• audio displays a volume bar and adds mouse actions to it.
• audio_input let's you manage which audio capture device to use and control its volume.
• bluetooth lets you connect to/disconnect paired bluetooth devices using bluetoothctl.
• ctl displays MPRIS metadata using playerctl
• input allows toggling on/off a list of devices managed through xinput or sysclient.
• mail shows the number of unread emails in all existent email mailboxes, allowing one to see a summary of them and their content as notifications.
• player-mpris-tail uses this script
• pkgs displays the number of XBPS packages to be updated.
• vpn helps connect/disconnect to wireguard interfaces through wg-quick.
• wm_preset can control BSPWM padding/window gap/border size through presets.

Overall, I'm very pleased with it, but in the near future I'd like to migrate some custom scripts to use ipc or ultimately move to lemonbar-xft as it provides fontconfig and anti-aliased features to lemonbar, which is way less memory hungry and more customisable overall.

• Shell - zsh

  • common: a simple, clean and minimal prompt
  • zsh-syntax-highlighting: fish shell like syntax highlighting for zsh
  • zsh-you-should-use: simple zsh plugin to remind you to use your shell aliases
  • zsh-interactive-cd: fish like interactive tab completion for cd

• Terminal emulator - kitty

  • Terminal multiplexer: tmux
    • rmuxinator: tmux project configuration utility

• Application launcher - rofi

  • rofi-file-browser-extended: rofi file-browser plugin
  • rbw: unofficial Bitwarden cli client
    • rofi-rbw: rbw frontend

• Text editor: neovim - extensible Vim fork. I currently manage my plugins with vim-plug:

  • nvim-lspconfig: nvim built-in LSP client. In my config I currently use the following language servers:
    • cssls
    • efm-langserver: general purpose Language Server
    • html
    • tsserver: TypeScript language server
    • vimls
  • completion-nvim: autocompletion framework for nvim built-in LSP, supporting LSP, path and ultisnips snippets completions.
  • nvim-treesitter: tree-sitter integration in nvim for syntax highlighting, indentation, folding and more.
  • emmet-vim: provide emmet-like expansions
  • fzf.vim: fzf vim integration
  • bullets.vim: manage bullet lists with custom keybindings.
  • vim-pandoc-syntax: provide markdown syntax highlighting and concealing independently of vim-pandoc.
  • vim-surround: easily edit surrounding punctuation pairs such as parenthesis, markup tags, and more.
  • defx.nvim: extremely customisable file explorer with Ueberzug and floating windows previews.
    • defx-icons: display filetype icons in defx buffers.
  • vim-commentary: consistent commenting experience in nvim.
  • closetag.vim: auto close tags. My use case are HTML and JSX tags.
  • auto-pairs: easily edit brackets, parens and quotes.
  • fugitive.vim for seamless Git integration in Vim
  • ultisnips: custom snippet solution for Vim

• MUA (Mail User Agent) - NeoMutt: CLI mail reader I decided to start to use a cli Mail User Agent as I disliked accessing my emails through a browser (potentially missing out on important notifications) and I wasn't satisfied with the GUI alternatives on Linux such as Thunderbird or Mailspring (Electron). I configured NeoMutt with vim-like keybindings and multi-account support. It should be noted that NeoMutt in and of itself wouldn't satisfy all of your needs, as its built-in IMAP support is quite slow in my experience and it doesn't have all the features other fancy desktop GUI mail clients do. Therefore, I use NeoMutt in conjunction with many other tools listed below, following the UNIX philosophy of having each program do one thing and do it well.

  • To fetch and perform a two-way synchronization of my IMAP mailboxes I use isync. With it, you are able to fetch emails from a remote email server and store them locally.

  It should be noted that most accounts work OOTB with this setup, but some Google accounts which implement a form of OAUTH2 (such as G-suite accounts), usually embed a special token into IMAP. The simplest way to solve this is, if your server admin hasn't disabled the feature, to add an App Password to your Google Account. To do this go to your account settings and navigate to Security > Signing in to Google > App passwords, and generate a new app password for a device. Then, you can simply replace your account's password through pass edit mail/{account} with the newly generated app password.

  If your Google Account is configured more strictly than this, you may want to have a look at this Arch Wiki section or this great post on OAUTH2.

  • abook: text-based addressbook with NeoMutt integration and autocompletion.
  • msmtp: SMTP client to send emails.
  • lynx: text-only browser I use to view HTML emails inside NeoMutt.
  • To listen on IMAP mailbox changes I use goimapnotify, a program which allows me to execute scripts when a new message is received by the mail server, for example. I use this to call isync on the accound where the new message is received, and therefore I can get real time notifications by including the following in my imapnotify_{account}.conf, which is based on my onm script and displays a notification of the latest email received. This is great as it prevents me from polling the email servers with a cronjob, which is far from efficient.

"onNewMailPost": "onm --latest {account}"

• File manager - vifm with personal fork of vifmimg which adds SVG file previews using inkscape. ueberzug is used for image previews.
• Fuzzy finder - fzf: extremely fast list filter, I use it to find files, directories, images, packages, among other as described in my zsh fzf settings in conjunction with these other tools:
  • fd: simple, fast and user-friendly alternative to find
  • proximity-sort: sort files based on current $PWD
  • ripgrep: regex pattern based search tool for files in current directory
  • bat: cat clone with syntax highlighting and Git integration
• Browser - Firefox

Firefox is the best browser in terms of privacy and customisation available. You can tweak the browser appearance through a userChrome.css file, I personally am a strong keyboard-only proponent so I've removed most of its UI buttons and features. Currently, I only have a single bar for everything I use, which includes a urlbar, a scrollable tab bar and a toggleable extensions overflow panel. One can also alter arbitrary web content through a userContent.css or even edit its behaviour with a user.js, which I use to harden some default settings in terms of security, tweak the default UI and improve the browser performance. The following is the list of addons I use and if applicable, its configuration file:

• Bitwarden: password manager. Note: for some reason, this is the only extension I can access through my keyboard with Ctrl+Shift+U.
• Cookie AutoDelete [config]: manage cookies and other storage settings on active tabs with support for Firefox Container Tabs.
• Stylus [config]: userstyles manager with live editor and support for CSS preprocessors.
• tridactyl [config]: this is my favourite addon for the amount of extensibility it provides, rather than just adding vim-like bindings to the browser. In my experience, it truly is a whole new control mechanism, as I'm able to do things such as:
  • Redirect rules using the webRequest API
  • Open hints with external commands, which I personally handle with my tri script allowing you to open media links with mpv, viewing PDF files with zathura, setting my desktop wallpaper on the fly, downloading files with curl, among others.
  • Open Firefox Container tabs automatically with custom rules.
  • Set custom search engines.
• uBlock Origin [config]: powerful content blocker with dynamic host filtering and custom filter lists.
• GTK3 theme - personal
• Image manipulation - GIMP
• Vector manipulation - Inkscape: FOSS vector drawing tool. It also provides a powerful cli that can convert SVGs to PNGs, which I use for vifm SVG previews.
• Image viewer - imv

I use imv in most of my scripts as it natively supports gifs and SVGs, but for some odd reason its .desktop file doesn't let me use it as my default image viewer as defined with xdg-mime default, so for the moment I'm using feh as a fallback.

• Media player - mpv

I mostly use it to play YouTube videos when accessed from the browser with a redirect rule set in Tridactyl. Additionally, I occassionally use straw-viewer as a YouTube cli client that uses the Invidious API, but it is quite unstable as of lately because Invidious development has almost stopped. To stream audio, I use tuner which provides search functionality for YouTube and Soundcloud without using their official APIs. Some of the scripts I use for mpv include

• mpv_thumbnail_script to show video preview thumbnails in the OSC.
• mpv_sponsorblock to fully support SponsorBlock on mpv.
• Music player - Music Player Daemon (MPD) and ncmpcpp as its client
• PDF reader - zathura
• Password manager - pass
• 2FA - pass-otp

I use an OTP pass extension as it lets me save my OTP keys with my other GPG encrypted passwords, and I like the fact that I can get OTP codes through the CLI, rather than having to download a standalone app on my phone or receive an SMS, the latter which I believe is a huge security threat.

Most services nowadays support both SMS or authenticator app 2FA verification. For example, on Google you just need to go to your account-setttings and then into Security > Signing in to Google > 2-Step Verification and change the Available second steps to an authenticator app, which in my case I have defaulted to an Authenticator on Android, as it seems to work. Additionally, in case I move systems, I have setup backup codes and saved them in my password manager.

To add an OTP key with pass-otp it's as easy as doing the following. Note that I found much easier to just pass the temporary key that these providers offer in case you cannot read a QR image, as I find the latter rather inconvenient.

pass otp insert -e otp/{account_name}
# Enter output:// URI for totp-secret:

And then we can simply enter an OTP URI in the form of otpauth://totp/{account_name}?secret={secret_key} where account_name usually is the email you use to log in to the service. Afterwards, you can simply do the following to generate a 2FA code and copy it to the primary clipboard

pass otp otp/{account_name} | tr -d '\n' | xclip -se c

• Wireless daemon - wpa_supplicant with dhcpcd

I tried to use IWD, which is said to be an optimized wireless daemon for Linux, but found it too unstable and had connection drops almost daily. It may have been caused by this bug or may be wireless card dependant, but for the moment I'm sticking with wpa_supplicant.

• Boot manager - rEFInd

Even though the default Void installation gives you the option to install GRUB, I chose to opt for rEFInd as it's better tailored to UEFI operating systems due to the fact that it doesn't provide a boot loader (something GRUB does) as the Linux kernel ships one since version 3.3.0. For its theme, I'm very fond of rEFInd-minimal-black.

• Audio server/mixer - PulseAudio

Recently, I tried to switch audio servers to sndio as Void compiles most of its packages with support for it. I must say, even though it's built on top of ALSA unlike its BSD counterpart, it makes the audio experience on Linux dead simple, offering ALSA master control, allowing having fallback devices and per application volume control. However, one major gripe I have with it is that it still doesn't support software ALSA PCMs, so projects like bluez-alsa which bring bluetooth compatibility to ALSA, don't work. During my attempt, I also tried to incorporate alsa-sndio and apulse for applications that don't support sndio or ALSA respectively, but the experience was not what I expected. Eventually, I decided to move back to PulseAudio for the time being.

• Keyboard firmware - QMK: provides keymaps to build custom firmwares for mechanical keyboards.
• Screenshot utility - maim
• Screencast utility - ffmpeg
• Drag and drop - dragon
• RSS feed reader - Newsboat
• pam-gnupg to unlock my GPG and SSH keys on login
• Task manager - Taskell for Kanban board task management
• Screen lock - XSecureLock
• System monitor - bottom
• Clibpoard utility - xclip
• VPN - wireguard
• VM management - virt-manager as a libvirt client for the QEMU virtualizer
• Chat clients
  • IRC/Matrix/Slack - WeeChat: extensible lightweight CLI chat client. I use the following plugins:
    • weechat-matrix
    • wee-slack
    • weechat-notify-send: receive desktop notifications with libnotify based on customisable conditions.
    • weechat-autosort: useful to autosort buffers in the buflist if you've configured many servers.
  • Signal: signal-cli with scli as its TUI
• cron daemon - chronie
• NTP daemon - chrony works better with intermittent connections and is more accurate than ntpd or OpenNTPD
• Syslog daemon - socklog is a small and secure syslogd alternative for runit
• Fonts

I managed to package all the fonts I use as Void templates, but in the case of Iosevka Nerd Font, some Font Awesome icons are being shown cut off in polybar because of this upstream issue with nerd-fonts, so for the moment I'm sticking with my local patched Iosevka Nerd Font.

• Iosevka Custom: main monospaced font
• Iosevka Nerd Font Complete: Powerline and Font Awesome icons in polybar
• IcoMoon Custom Pack: custom icons in Polybar from IcoMoon
• Google Noto Emoji Fonts: adds emoji support

• Cursor - Bibata
• Icon theme - Papirus
• Unit conversion - GNU Units
• Burner SMS - tmpsms
• Package managers
  • yarn: a faster JavaScript package manager. Global dependencies include
    • mocha: JavaScript test framework
    • ESLint: JavaScript linter tool
    • Prettier: JavaScript code formatter
    • vim-language-server
    • css-language-server
    • typescript-language-server
    • typescript
    • html-languageserver
  • luarocks: Lua package manager
    • luacheck: Lua linting and static analysis

XDG Base Directory

When possible, I try to stick to software that implements the basics of the XDG Base Directory specification as I'd much rather have an uncluttered $HOME directory and have an overall consistent file structure. Therefore, for those programs that do not directly support it, I've defined various environment variables or shell aliases that work around the issue in .aliases.

Scripts

• au

Wrapper around various PulseAudio, ALSA and sndio utilities, providing mixer volume control, change of capture source, managing bluetooth devices and integration with polybar modules. It was originally meant to be used with the get_au_sv --auto option, which detects the audio server and configures the bar modules/bindings on the fly, but I found it quite resource heavy, so for now you need to pass the audio server being used manually.

• cast

Wrapper around ffmpeg that helps record fullscreen with/without audio, regions of the screen using slop, as well as converting screencasts to .gif format and allows to lower their resolution. It also provides assigning a cover art to an mp3 file.

• color

Color utility that uses colorpicker to choose and preview any color in the screen and yad as a simple colorpicker tool. Both copy the output color to the clipboard using xclip.

• ctc

Color conversion utility, which can convert hex colors to RGB format, and RGB colors to float format.

• dg

Provides the ability to download a file by dropping it into a dragon window.

• dlm

Small media utility that helps download part of a song from youtube-dl supported services or crop a local media file.

• input

Enable/disable devices using xinput or sysclient. Provides integration with polybar modules.

• key

Wrapper around screenkey.

• onm

Displays email notifications on arrival with the help of goimapnotify, fetches all unread emails from all active mailboxes with the help of isync and displays a summary. Provides integration with polybar modules.

• ro

Makes use of Rofi's dmenu mode to show different applets, which include some of the following

• A help guide for current sxhkd bindings
• Powermenu
• PulseAudio sink/source selector
• Recent unread email menu
• tmux session selector
• VPN selector for wireguard interfaces
• Wi-Fi menu through wpa_supplicant

• sc

Wrapper around maim to take region and fullscreen screenshots and copy its path to the clipboard for easier media upload in cli chat clients.

• sl

Sets up scli with signal-cli by automatically displaying the QR code to be read by the Signal mobile client.

• sy

Custom system information tool that displays current OS, uptime, WM, CPU, RAM, among other features.

• term

Small utility to display a terminal over an active window with its same dimensions.

• tri

Provides Tridactyl utilities that can be consumed with in a tridactylrc with its Native messenger installed, such as handling links to determine what external application to open them with, setting my desktop wallpaper from a browser image and downloading media.

• wm

Utilities for BSPWM, such as controlling the window borders/gap/padding, listening on subscription events to set up workspaces on connected monitors, as well as being able to set desktop presets and providing polybar integration.

• wp

A small tool to set a solid/image wallpaper.

• wt

Fetch the current location and use wttr.in to get its live weather.

Self-hosted

I've included some of the files I use to self host services in my personal VPS in this directory. These are useful to deploy docker containers through Docker Compose configuration files.

Note that most of the times, these docker-compose.yml files mount volumes from the container to the host, so configuration files are automatically created in the specified directories after running docker-compose up -d in the correspondent service directory.

Also, all containers share the same Docker network controlled by the environment variable DOCKER_NETWORK so they can communicate with Caddy and therefore there is no need to expose these container's ports directly in the host.

The services included are:

• bitwarden_rs: an unofficial lightweight selfhostable Bitwarden server to manage my passwords compatible with its web vault, browser extensions and mobile clients.
• Caddy 2: web server with built-in TLS certificates, file server, reverse proxying, load balancing, caching and many more capabilities. I've used nginx and apache in the past and caddy is hands down the most straightforward solution, seamlessly integrating in a container infrastructure due to its dependency-free nature.
• gitea: self-hosted Git service
• jitsi: FOSS video/audio bridge
• mailcow: self-hosted email server suite
• matrix: decentralized real-time communication protocol with E2EE, messaging, VoIP and bridging capabilities with other protocols
  • synapse: Matrix reference homeserver
  • element: web-based Matrix client with E2EE cross-signing
  • dimension: open-source Matrix integration manager
  • synapse admin: UI to manage one's Synapse database
• seafile: self-hosted file sync system with support for encryption, selective sharing, teamwork features, automatic snapshots, WYSIWG editor and various clients, including a Linux CLI
• watchtower: process to automate container images updates
• whoogle: self-hosted metasearch engine with Google search results