About

For those seeking documentation, the ArchWiki is the best resource available. In fact, it's so good that it can be a perfect trap for the curious people. My goal here is to gather the information I find relevant for my own use case, allowing me to setup and maintain a simple and aesthetic Arch Linux Wayland environment while minimizing the chances of falling down a rabbit hole.

it's called "dotfiles" because that folder ".config" starts with a dot and is therefor hidden

and we customize these hidden text files for ~20 programs because we're neurotic lovers of beauty 🤷

-- from a Reddit user on r/unixporn

Components

The main building blocks, a.k.a packages¹

System

Boot Manager: rEFInd
Dotfile Manager: Chezmoi
Initramfs Generator: Booster
UKI Generator: systemd-ukify

Desktop

App Launcher: Fuzzel
Wayland Compositor: Niri
Display Manager: Ly
Notification: Mako
Screen Locker Swaylock
Status Bar: Waybar

Theme

Cursor: Breeze
Fonts and Glyphs: FiraMono Nerd Font
Gtk: Materia-dark
Icons: Papirus
Palette: Catppuccin Mocha

Terminal

Prompt: Starship
Shell: Fish
Terminal Emulator: Alacritty

Tools

Browser: Firefox
File Manager: Yazi
Text Editor: Neovim

Clients

BitTorrent: Transmission
Discord: Vesktop
Spotify: Ncspot

Utilities and Quality of Life

Bat: Cat clone with syntax highlighting and git integration
Bob: A version manager for neovim
Bottom: A graphical process/system monitor
Cava: Console-based Audio Visualizer for Alsa
Delta: A syntax-highlighting pager for git, diff, grep, and blame output
Eza: A modern replacement for ls (community fork of exa)
Fastfetch: Like Neofetch, but much faster because written in C
Fd: Simple, fast and user-friendly alternative to find
Fzf: Command-line fuzzy finder
Gitui: Blazing fast terminal-ui for git written in Rust
Ripgrep: A search tool that combines the usability of ag with the raw speed of grep
Yay: Yet another yogurt. Pacman wrapper and AUR helper written in go
Zoxide: A smarter cd command for your terminal

For the exhaustive package list, you can check the packages.toml

Live USB

Creating a bootable USB containing the ISO

Download the ISO file from the Arch Linux website
Find the USB drive name

ls -l /dev/disk/by-id/usb-*

Make sure it is not mounted (the MOUNTPOINTS column should be empty)

lsblk

Write the ISO to the USB drive

sudo pv path/to/archlinux-version-x86_64.iso -Yo /dev/disk/by-id/usb-My_flash_drive-0:0

Notes

The BitTorrent Download is the recommended option and the file will look like this: archlinux-version-x86_64.iso.torrent
The USB drive name should look something like /dev/disk/by-id/usb-SanDisk_Cruzer_Blade_4C530000100920118104-0:0. Make sure to not append any partition like -part1

Live Environment

Improve the default font size

setfont ter-222b

Change the default keyboard layout (US), if necessary

# for example, to set a brazilian keyboard layout
loadkeys br-abnt2

Make sure the system is booted in UEFI mode

# the output should be 64 for 64-bit system
cat /sys/firmware/efi/fw_platform_size

Connect to the internet

For ethernet, just plug in the cable

For wifi, use iwctl interactive prompt

iwctl

# this command will not output anything
station wlan0 scan

# check the available networks
station wlan0 get-networks

# connect
station wlan0 connect "SSID"

# check the connection
station wlan0 show

# Ctrl+d works too
exit

Check the internet connection

ping archlinux.org

Ensure the system clock is synchronized

timedatectl

Notes

You can check the available keyboard layouts running localectl list-keymaps

Partitions

Always make sure to identify and select the correct device.

Otherwise, the following steps may result in unintended data loss.

Identify available disks

# rom, loop or airootfs may be ignore
lsblk

The next step is for NVMe drives only

Check the formatted logical block address (LBA) size

nvme id-ns -H /dev/nvme0n1 | grep "Relative Performance"

On the output example below the sector size in use (512 bytes) is not the optimal one:

LBA Format  0 : Metadata Size: 0   bytes - Data Size: 512 bytes - Relative Performance: 0x2 Good (in use)
LBA Format  1 : Metadata Size: 0   bytes - Data Size: 4096 bytes - Relative Performance: 0x1 Better

You can confirm it by running lsblk -td and looking at the LOG-SEC column value.

To change the logical block address size, you can use the nvme format command specifying the preferred value with the --lbaf parameter:

nvme format --lbaf=1 /dev/nvme0n1

Create the partitions

cfdisk /dev/the_disk_to_be_partitioned

Purpose	Suggested size	Partition type	Mount point
efi	1 GiB	EFI System	/efi
swap	8 GiB	Linux filesystem	[SWAP]
root	Remainder	Linux filesystem	/

Verify the partitions

fdisk -l /dev/partitioned_disk

Create an Ext4 fs for the root

mkfs.ext4 /dev/root_partition

Initialize the swap

mkswap /dev/swap_partition

Format the efi to FAT32

mkfs.fat -F 32 /dev/efi_system_partition

Add a label to the efi partition

# This will be useful later on to set the rEFInd config
dosfslabel /dev/efi_system_partition ARCHIE_ESP

Add a label to the root partition

# This will be useful later on to set the root device
e2label /dev/root_partition ARCHIE_ROOT

Verify the result

lsblk --fs /dev/partioned_disk

Mount the root partition to /mnt

mount /dev/root_partition /mnt

Mount the efi partition to /mnt/efi

mount --mkdir /dev/efi_system_partition /mnt/efi

Enable the swap

swapon /dev/swap_partition

Check the mountpoints

lsblk /dev/partioned_disk

Notes

To identify available disks, the fdisk -l command provides all the necessary information, but lsblk is also a good alternative for a concise output
Make sure to set the correct type for the efi partition

Installation

Update the mirrorlist

reflector --protocol https --verbose --latest 25 --sort rate --save /etc/pacman.d/mirrorlist

Install the essential packages to the new root

pacstrap -K /mnt base linux linux-firmware

And also:

base-devel
git
amd-code / intel-ucode
booster
busybox
systemd-ukify
mesa
vulkan-radeon / nvidia
networkmanager
nano
refind

Generate an fstab file

genfstab -U /mnt >> /mnt/etc/fstab

Change root into the new system

arch-chroot /mnt

Set the time zone

# Example for UTC-3
ln -sf /usr/share/zoneinfo/Brazil/East /etc/localtime

Check the new local time

date

Generate the /etc/adjtime

hwclock --systohc

Set up time synchronization

systemctl enable systemd-timesyncd.service

Edit the locale.gen file, uncommenting all the needed UTF-8 locales

nano /etc/locale.gen

en_US.UTF-8 UTF-8
#en_US ISO-8859-1

Generate the locales

locale-gen

Create the locale.conf file, setting the LANG variable accordingly

nano /etc/locale.conf

LANG=en_US.UTF-8

Create the /etc/vconsole.conf file, if a different keyboard layout is required

nano /etc/vconsole.conf

KEYMAP=br-abnt2

Create the hostname file

nano /etc/hostname

desktop

Set the root password

passwd

Create a new user, adding it to the wheel group

useradd -m -G wheel <username>

Add a password to the user

passwd <username>

Edit the sudoers configuration file

EDITOR=nano visudo

## Uncomment to allow members of group wheel to execute any command
%wheel ALL=(ALL:ALL) ALL

Install systemd-boot

bootctl install

Install rEFInd

refind-install

Set booster configuration file

nano /etc/booster.yaml

extra_files: busybox,fsck,fsck.ext4
modules_force_load: amdgpu,hid_generic,usbhid

for nvidia gpu, replace amdgpu accordingly:

modules_force_load: nvidia,nvidia_modeset,nvidia_uvm,nvidia_drm,hid_generic,usbhid

Set the install.conf file

nano /etc/kernel/install.conf

layout=uki
uki_generator=ukify

Set the ukify configuration

nano /etc/kernel/uki.conf

[UKI]
Initrd=/boot/booster-linux.img
Microcode=/boot/<amd/intel>-ucode.img
Splash=/usr/share/systemd/bootctl/splash-arch.bmp

Include the device and other kernel parameters to the cmdline

nano /etc/kernel/cmdline

root=LABEL=ARCHIE_ROOT nvme_load=YES nowatchdog rw quiet

Verify the current kernel-install configuration

kernel-install inspect

Check the current available boot entries

bootctl list

Enable the NetworkManager service

systemctl enable NetworkManager

Exit the chroot environment

exit

Unmount all the partitions

umount -R /mnt

Reboot

reboot

good luck !

for laptop only

Use nmcli to list and to connect to available Wi-Fi networks

nmcli device wifi list

nmcli device wifi connect <SSID> password <password>

Enable the tlp service

systemctl enable tlp.service

Mask the rfkill service

systemctl mask systemd-rfkill.service

systemctl mask systemd-rfkill.socket

Download fastfetch

sudo pacman -S fastfetch

Run it

fastfetch

enjoy your new achievement !

Notes

A good reference for essential packages is to check the ones available in the Arch Linux live system (ISO). You can find them here Another good source is to check the packages available in the EndeavourOS ISO. You can find them in their repo
Jokes aside, the last step is a simple and efficient way to verify your installation

Pos-Installation

Create the themes directory for refind

cd /efi/EFI/refind

On refind installation path, clone the catppuccin repo inside a themes directory

mkdir themes && cd themes

git clone https://github.com/catppuccin/refind.git catppuccin

Edit the mocha.conf file, commenting the last line

nano catppuccin/mocha.conf

#showtools hidden_tags

Edit the refind.conf, making sure to add a new menuentry for the systemd-boot and also including the mocha.conf file

nano ../refind.conf

timeout 5

[...]

menuentry "Arch Linux" {
    icon /EFI/refind/themes/catppuccin/assets/mocha/icons/os_arch.png
    volume "ARCHIE_ESP"
    loader /EFI/systemd/systemd-bootx64.efi
}

include themes/catppuccin/mocha.conf

Install some compilers

sudo pacman -S clang go lua rustup

rustup update stable

Update the loader.conf file

sudo nano /efi/loader/loader.conf

timeout 1
console-mode auto

Install pacman-contrib

sudo pacman -S pacman-contrib

Enable the paccache.timer to periodically clean the pacman cache

systemctl enable paccache.timer

Update pacman configuration file

sudo nano /etc/pacman.conf

# Misc options
#UseSyslog
Color
ILoveCandy
#NoProgressBar
#CheckSpace
VerbosePkgLists
ParallelDownloads = 5

Update the database

pacman -Sy

Install yay

git clone https://aur.archlinux.org/yay.git && cd yay && makepkg -si

Install extra pacman hooks

yay -S pacman-hook-kernel-install

Reinstall the kernel package to trigger the unified kernel image hooks

sudo pacman -S linux

Check the current available boot entries

sudo bootctl list

Notes

For some reason the rEFInd showtools variable is not working properly for me anymore, this is why I have to comment that line on catppucin's mocha file
An example for the pacman.conf file can be found on EndeavourOS repo. If you plan to use packages like steam, make sure to enable (uncomment) the [multilib] repository

Home Sweet Home

Install chezmoi

sudo pacman -S chezmoi

Initialize it

chezmoi init https://github.com/<user>/dotfiles.git

Apply the changes

chezmoi apply

just watch the magic happen

Reboot the system

reboot

Launch niri from the tty

niri-session

Check if fish is in the valid shells list

cat /etc/shells

Set fish as login shell

chsh -s /usr/bin/fish <user>

Check it

getent passwd $USER | cut -d: -f7

Refresh the font cache to make sure the fonts are available system-wide

sudo fc-cache -fv

Install xwayland-satellite

git clone https://github.com/Supreeeme/xwayland-satellite.git

cd xwayland-satellite && cargo build --release -F systemd

cd target/release && sudo cp xwayland-satellite /usr/bin/

Download Bitwarden firefox extension
Login into Firefox
Apply Catppuccin Mocha Mauve color theme to Firefox by clicking here
Generate a new SSH key

ssh-keygen -t ed25519 -C "your_email@example.com"

Check the public key

cat ~/.ssh/id_ed25519.pub

Use github to test the SSH connection

ssh -T git@github.com

Rebuild bat cache to include catppuccin's syntax highlighting

bat cache --build

Check if it's now available

bat --list-themes | rg "Catppuccin"

Fetch Yazi plugins

ya pack -i

ya pack -u

Install and set Neovim nightly

bob install nightly

sudo bob use nightly

Increase inotify maximum values

sudo nano /etc/sysctl.conf

fs.inotify.max_queued_events=524288
fs.inotify.max_user_watches=524288

Launch Neovim to fetch its configuration

nv

Include the api-key for the WakaTime plugin

# launch the website and copy the api key
open https://wakatime.com/api-key

# run the following cmd inside neovim and paste the key
WakaTimeApiKey

Enable the bluetooth service

systemctl enable bluetooth.service

Update the main.conf file to set the startup state as off

sudo nano /etc/bluetooth/main.conf

[Policy]
AutoEnable=false

Enable the ly service

systemctl enable ly

Reboot the system

reboot

there's no place like home

Miscellaneous

Profile-sync-daemon

I haven't had much luck with this so far.

I've tried it twice, and Firefox became very unstable.

Edit the sudoers adding the necessary rights to the end of the file

EDITOR=nvim sudo visudo

lpnh ALL=(ALL) NOPASSWD: /usr/bin/psd-overlay-helper

Check psd current status

psd preview

Enable the psd service

systemctl --user enable psd.service

NetworkManager

Wi-Fi Connection

Get the list of available Wi-Fi networks

nmcli device wifi list

Connect to a Wi-Fi

nmcli device wifi connect <SSID_or_BSSID> password <password>

Update the DNS

Get the list of the current active profiles

nmcli connection show --active

Check the current DNS values

nmcli connection show 'NAME' | rg dns

Update the DNS

nmcli connection modify 'NAME' ipv4.dns "8.8.8.8 1.1.1.1"

Reconnect

nmcli connection down 'NAME'

nmcli connection up 'NAME'

Rust

Toolchains

Install the nightly channel

rustup toolchain install nightly

Check the installed toolchains

rustup toolchain list

Targets

Include support for the Wasm target

rustup target add wasm32-unknown-unknown

Check the installed targets

rustup target list --installed

Virtual Machine

Check the hardware virtualization support

# the output should be > 0
grep -Ec '(vmx|svm)' /proc/cpuinfo

Make sure the virtualization is enabled in the BIOS

For AMD, look for the SVM option. For Intel, look for the VMX option

Install the necessary packages

sudo pacman -Syu virt-manager qemu-desktop dnsmasq iptables-nft

Enable the libvirtd service

sudo systemctl enable --now libvirtd.service

Add the user to the libvirt group

sudo usermod -aG libvirt $env.USER

Restart the service

systemctl restart libvirtd.service

dotfiles cookbook