Configuring bspwm Window Manager on Alpine Linux 🪟

Bspwm (Binary Space Partitioning Window Manager) is like having a smart assistant that organizes your windows automatically! 🤖 It’s a tiling window manager that arranges windows without overlapping, making your desktop super efficient. Let’s set up a beautiful and functional bspwm environment on Alpine Linux! 🚀

What is bspwm? 🤔

Bspwm features:

• Tiling windows - Automatically arranges windows
• Keyboard driven - Control everything with hotkeys
• Minimal and fast - Uses very few resources
• Highly customizable - Configure every aspect
• Dynamic workspaces - Create workspaces on the fly

Think of it as a window organizer that never lets windows overlap! 📐

Installing bspwm and Dependencies 📦

Let’s install everything we need:

# Update package list
sudo apk update

# Install bspwm and sxhkd (hotkey daemon)
sudo apk add bspwm sxhkd

# Install terminal emulator
sudo apk add alacritty
# Or alternatives:
# sudo apk add st xterm rxvt-unicode

# Install additional utilities
sudo apk add dmenu feh picom polybar

# Install X server if not already installed
sudo apk add xorg-server xf86-input-libinput xinit

Basic bspwm Configuration 🔧

Create the configuration files:

# Create config directories
mkdir -p ~/.config/bspwm ~/.config/sxhkd

# Create bspwm config
cat > ~/.config/bspwm/bspwmrc << 'EOF'
#!/bin/sh

# Monitor setup
bspc monitor -d I II III IV V VI VII VIII IX X

# Window settings
bspc config border_width         2
bspc config window_gap          12
bspc config split_ratio          0.52
bspc config borderless_monocle   true
bspc config gapless_monocle      true

# Colors
bspc config normal_border_color   "#44475a"
bspc config active_border_color   "#6272a4"
bspc config focused_border_color  "#8be9fd"
bspc config presel_feedback_color "#50fa7b"

# Rules
bspc rule -a Firefox desktop='^2'
bspc rule -a Gimp state=floating
bspc rule -a mplayer2 state=floating

# Autostart
pgrep -x sxhkd > /dev/null || sxhkd &
picom &
polybar example &
feh --bg-scale ~/wallpaper.jpg &
EOF

# Make it executable
chmod +x ~/.config/bspwm/bspwmrc

Setting Up Hotkeys with sxhkd 🎹

Configure keyboard shortcuts:

cat > ~/.config/sxhkd/sxhkdrc << 'EOF'
# Terminal emulator
super + Return
    alacritty

# Program launcher
super + d
    dmenu_run

# Reload sxhkd config
super + Escape
    pkill -USR1 -x sxhkd

# Quit/restart bspwm
super + alt + {q,r}
    bspc {quit,wm -r}

# Close and kill
super + {_,shift + }w
    bspc node -{c,k}

# Toggle tiled/monocle layout
super + m
    bspc desktop -l next

# Send to desktop
super + {_,shift + }{1-9,0}
    bspc {desktop -f,node -d} '^{1-9,10}'

# Focus node in direction
super + {h,j,k,l}
    bspc node -f {west,south,north,east}

# Move node in direction
super + shift + {h,j,k,l}
    bspc node -s {west,south,north,east}

# Expand window
super + alt + {h,j,k,l}
    bspc node -z {left -20 0,bottom 0 20,top 0 -20,right 20 0}

# Contract window
super + alt + shift + {h,j,k,l}
    bspc node -z {right -20 0,top 0 20,bottom 0 -20,left 20 0}

# Toggle floating/fullscreen
super + {s,f}
    bspc node -t {floating,fullscreen}

# Focus next/previous window
alt + {_,shift + }Tab
    bspc node -f {next,prev}.local

# Rotate tree
super + {r,shift + r}
    bspc node @/ -R {90,-90}
EOF

Creating a Polybar Configuration 📊

Set up a status bar:

# Create polybar config
mkdir -p ~/.config/polybar
cat > ~/.config/polybar/config << 'EOF'
[colors]
background = #282a36
foreground = #f8f8f2
primary = #bd93f9
alert = #ff5555

[bar/example]
width = 100%
height = 24
fixed-center = true
background = ${colors.background}
foreground = ${colors.foreground}

padding-left = 0
padding-right = 2
module-margin-left = 1
module-margin-right = 2

font-0 = "JetBrains Mono:size=10;2"
font-1 = "Font Awesome 6 Free:style=Solid:size=10;2"

modules-left = bspwm
modules-center = date
modules-right = cpu memory battery

[module/bspwm]
type = internal/bspwm
label-focused = %index%
label-focused-background = ${colors.primary}
label-focused-padding = 2
label-occupied = %index%
label-occupied-padding = 2
label-urgent = %index%!
label-urgent-background = ${colors.alert}
label-urgent-padding = 2
label-empty = %index%
label-empty-foreground = #44475a
label-empty-padding = 2

[module/cpu]
type = internal/cpu
interval = 2
format-prefix = " "
label = %percentage:2%%

[module/memory]
type = internal/memory
interval = 2
format-prefix = " "
label = %percentage_used%%

[module/date]
type = internal/date
interval = 5
date = %Y-%m-%d
time = %H:%M
label =  %date%  %time%

[module/battery]
type = internal/battery
battery = BAT0
adapter = AC
format-charging = <label-charging>
format-discharging = <label-discharging>
label-charging =  %percentage%%
label-discharging =  %percentage%%
EOF

Starting bspwm 🚀

Create an X session file:

# Create .xinitrc
cat > ~/.xinitrc << 'EOF'
#!/bin/sh

# Set keyboard layout (optional)
setxkbmap us

# Start bspwm
exec bspwm
EOF

# Start X and bspwm
startx

Window Management Tips 🎯

Creating Layouts

# Split horizontally
super + h  # Then open new window

# Split vertically  
super + v  # Then open new window

# Create preset split
super + ctrl + {h,j,k,l}

# Cancel preset
super + ctrl + space

Managing Workspaces

# Add to bspwmrc for dynamic workspaces
bspc config remove_disabled_monitors true
bspc config remove_unplugged_monitors true

# Create new workspace
bspc monitor -a newspace

# Remove empty workspace
bspc desktop -r

Customizing Appearance 🎨

Setting Wallpaper

# Download a wallpaper
wget https://example.com/wallpaper.jpg -O ~/wallpaper.jpg

# Set wallpaper (add to bspwmrc)
feh --bg-scale ~/wallpaper.jpg

Window Gaps and Borders

# Dynamic gap adjustment (add to sxhkdrc)
super + {minus,equal}
    bspc config window_gap $(($(bspc config window_gap) {-,+} 5))

# Toggle gaps
super + g
    bspc config window_gap {0,12}

Installing Additional Tools 🛠️

Rofi (Application Launcher)

# Install rofi
sudo apk add rofi

# Replace dmenu with rofi in sxhkdrc
super + d
    rofi -show drun

# Configure rofi
mkdir -p ~/.config/rofi
rofi -dump-config > ~/.config/rofi/config.rasi

Compositor for Effects

# Picom configuration
mkdir -p ~/.config/picom
cat > ~/.config/picom/picom.conf << 'EOF'
# Shadows
shadow = true;
shadow-radius = 7;
shadow-opacity = 0.6;

# Fading
fading = true;
fade-delta = 5;

# Transparency
inactive-opacity = 0.9;
active-opacity = 1.0;

# Backend
backend = "glx";
vsync = true;
EOF

Creating Custom Scripts 📝

Workspace Switcher

cat > ~/.local/bin/workspace_switcher << 'EOF'
#!/bin/sh
# Interactive workspace switcher

workspace=$(bspc query -D --names | dmenu -p "Switch to workspace:")
[ -n "$workspace" ] && bspc desktop -f "$workspace"
EOF

chmod +x ~/.local/bin/workspace_switcher

Window Selector

cat > ~/.local/bin/window_select << 'EOF'
#!/bin/sh
# Select window with dmenu

window=$(bspc query -N -n .window | \
    xargs -I{} sh -c 'echo "{} $(xprop -id {} WM_CLASS | cut -d\" -f4)"' | \
    dmenu -p "Select window:" | \
    cut -d' ' -f1)

[ -n "$window" ] && bspc node -f "$window"
EOF

chmod +x ~/.local/bin/window_select

Troubleshooting Common Issues 🔧

Black Screen After Login

# Check X server logs
cat ~/.local/share/xorg/Xorg.0.log

# Verify bspwm is executable
chmod +x ~/.config/bspwm/bspwmrc

# Test configuration
bspwm -c ~/.config/bspwm/bspwmrc

Hotkeys Not Working

# Check if sxhkd is running
pgrep sxhkd

# Test sxhkd configuration
sxhkd -c ~/.config/sxhkd/sxhkdrc

# Debug mode
killall sxhkd
sxhkd -s /tmp/sxhkd.fifo &

Advanced Configuration 🚀

Multi-monitor Setup

# Add to bspwmrc
if xrandr | grep "HDMI1 connected"; then
    xrandr --output HDMI1 --auto --right-of eDP1
    bspc monitor eDP1 -d I II III IV V
    bspc monitor HDMI1 -d VI VII VIII IX X
fi

External Rules

# Create external rules script
cat > ~/.config/bspwm/external_rules << 'EOF'
#!/bin/sh

wid=$1
class=$2
instance=$3

case "$class" in
    Firefox)
        echo "desktop=^2 follow=on"
        ;;
    Zathura)
        echo "state=tiled"
        ;;
esac
EOF

chmod +x ~/.config/bspwm/external_rules

# Add to bspwmrc
bspc config external_rules_command ~/.config/bspwm/external_rules

Quick Reference Cheat Sheet 📋

# Window focus
super + {h,j,k,l}         # Focus direction
alt + Tab                 # Cycle windows

# Window movement
super + shift + {h,j,k,l} # Move window
super + {1-9}            # Switch workspace
super + shift + {1-9}    # Move to workspace

# Window states
super + t                # Tiled
super + s                # Floating
super + f                # Fullscreen
super + m                # Monocle

# System
super + alt + r          # Restart bspwm
super + alt + q          # Quit bspwm

Conclusion 🎯

You now have a fully functional bspwm setup on Alpine Linux! With tiling windows, custom hotkeys, and a sleek appearance, your desktop is now a productivity powerhouse. Remember to customize the configuration to match your workflow. Happy tiling! 🪟✨