🪟 openbox-setup

A complete Openbox configuration script for Debian-based systems. Includes a wallpaper-driven theme engine, a quickshell bar, smart automation, dynamic menus, and sane keybindings — fully set up in minutes.

Part of the JustAGuy Linux window manager collection — installable standalone or via butterknife, the installer for Butterbian.

---

🚀 Installation

git clone https://justaguy.dev/drew/openbox-setup.git
cd openbox-setup
chmod +x install.sh
./install.sh

⚠️ XLibre users: This script installs xorg as part of its core packages, which will replace XLibre if you've installed it. Remove xorg from PACKAGES_CORE in install.sh before running, or use --only-config to skip package installation entirely.

This assumes a fresh Debian or Debian-based install with sudo access.

---

📦 What It Installs

Component	Purpose
openbox	Lightweight window manager
picom (yshui)	Compositor for transparency
quickshell	Bar + popups (wallpaper-themed)
kitty	Terminal emulator (default)
thunar + plugins	File manager
xfce4-appfinder	Application launcher
firefox-esr	Default web browser
geany + plugins	Lightweight IDE
dunst	Notifications
rofi	Keybind help viewer
nala	Better apt frontend
fastfetch	System info utility
pipewire	Audio handling
flameshot,	Screenshot tools
micro	Terminal text editor
redshift	Night light
qimgv	Lightweight image viewer
fzf, etc.	Utilities & enhancements
obmenu-generator	Dynamic right-click menu
GTK & icon themes	Cohesive look and feel

📄 Need help with Geany? See the full guide at justaguylinux.com/documentation/software/geany

---

🎨 Appearance & Theming

The wallpaper is the theme. Right-click the launcher icon (or press Super + Shift + T), pick a wallpaper, and everything re-themes to match — live, no logout:

• the bar and its popups
• Openbox titlebars, borders, buttons, and the right-click menu (a window theme is generated from the palette and hot-reloaded)
• kitty, rofi, and dunst
• GTK applications — a recolored Orchis theme
• icons — the closest-matching Colloid variant

Flat, designed wallpapers (logo art) reproduce their exact colors; photos get a muted, hand-tuned treatment. Middle-click the launcher for a random pick. Drop your own images into ~/.config/openbox/wallpaper/ and they appear in the picker — no theme files to edit, ever.

💡 Special thanks to vinceliuice for the excellent GTK and icon themes.

---

🔑 Keybindings Overview

Shortcut	Action
Super + Return	Launch terminal (kitty)
Super + Space	Launch XFCE app finder
Super + /	Open keybind help via Rofi
Super + Arrow Keys	Snap window to side/center
Super + 1-0, -, =	Switch to desktop 1-12
Super + Shift + 1-0, -, =	Move window to desktop 1-12
Super + Shift + T	Wallpaper picker (re-themes everything)
Super + N	Network app (wifi / VPN)
Print / Super + s	Screenshot (fullscreen)
Super + Print / Super + Shift + s	Screenshot (region select)
XF86Audio*	Multimedia key support

The bar is clickable too — weather (forecast / settings), volume, network, notifications (bell), and calendar (clock) each have their own popup. Details in ~/.config/openbox/quickshell/README.md.

Keybindings are defined in:

• ~/.config/openbox/rc.xml
• ~/.config/openbox/scripts/help (invoked by Super + /)

---

📂 Configuration Files

~/.config/openbox/
├── rc.xml                 # Main Openbox configuration
├── autostart              # Startup applications
├── environment            # Session environment variables
├── menu.xml               # Static fallback menu
├── wallpaper/             # Default and user wallpapers
├── dunst/                 # Notification config
│   └── dunstrc
├── picom/                 # Compositor configuration
│   └── picom.conf
├── quickshell/            # Bar + popups (see its README)
├── quickshell-network/    # Network app (wifi / VPN)
├── polybar/               # Retired fallback bar (commented in autostart)
├── rofi/                  # Rofi launcher + keybind theme
│   ├── config.rasi
│   └── keybinds.rasi
├── scripts/               # Helper tools
│   ├── wallpaper-theme    # The theme engine (palette → everything)
│   ├── bar                # Bar restart / log helper
│   ├── network            # Network app toggle
│   ├── weather            # Weather location & units (rofi)
│   ├── changevolume
│   ├── power
│   └── help
└── obmenu-generator/      # Dynamic menu config
    └── schema.pl
    
~/.config/kitty/
└── kitty.conf               # Terminal configuration

---

🔍 HiDPI / 4K Displays

On a 4K screen, type can come up tiny. There's no single fix — openbox itself doesn't scale, so each toolkit (X fonts, GTK, Qt, the cursor) has to be told separately, which is why one-line suggestions tend to fix some apps but not all.

~/.config/openbox/environment ships a commented HiDPI block at the bottom. Uncomment it and log out / back in — it's sourced before openbox starts, so the whole session picks it up. It sets Xft.dpi (X apps, fonts, cursor), GDK_SCALE/GDK_DPI_SCALE (GTK apps), and QT_AUTO_SCREEN_SCALE_FACTOR (Qt apps) together. The defaults are ~200%; comments in the block show how to dial it to ~150%. The quickshell bar follows Qt scaling (QT_AUTO_SCREEN_SCALE_FACTOR).

---

🧠 Notes

• Menu is dynamically generated via obmenu-generator -p -i — it includes a Shell section (wallpaper picker, network, weather, power)
• If the bar ever misbehaves: right-click the desktop → Openbox → Restart Bar (or run ~/.config/openbox/scripts/bar restart)
• Weather auto-locates by IP (VPNs skew this) — right-click the weather module to pin a city or switch °F/°C
• Wallpapers are stored in ~/.config/openbox/wallpaper/
• You can launch a keybind viewer anytime with Super + /
• On first login, a welcome notification points to ~/QUICKSTART-openbox.md — a short cheat sheet you can delete when you're comfortable

---

License

GPL-2.0 - See LICENSE for details.

Support

Connect

• YouTube — tutorials and guides
• Butterforge — source code and projects
• The Butter Lab — Discourse forum
• The Churn — community chat (Fluxer)
• Wiki — documentation and guides
• Mastodon — @justaguylinux@fosstodon.org
• Butterbian — a Debian-based distro

---

Made with butter by JustAGuyLinux