🌟 AwesomeWM Dotfiles • ミツキナノカ's Desktop Environment

A meticulously crafted, production-ready AwesomeWM desktop environment featuring modern aesthetics, smooth animations, and optimized performance for Arch Linux.

📸 Screenshots

Desktop Overview	System Information	Dashboard	Lock screen

Clean Catppuccin Mocha theme	Custom fastfetch configuration	Integrated dashboard & controls	Integrated lock screen

✨ Key Features

🎨 Visual Design

🌙 Catppuccin Mocha Theme - Carefully balanced dark color palette
🎭 BeautyLine Icons - Consistent, modern icon theme throughout the system
🔤 JetBrains Mono Nerd Font - Programming-focused typography with icon support
🔔 Elegant Notifications - Modern naughty with popup

⚡ Performance & Efficiency

🚀 Optimized Resource Usage - Minimal memory footprint with smart window management
🎯 Hardware Acceleration - GLX backend with GPU-accelerated rendering
⚙️ Modular Architecture - Clean Lua configuration split across logical modules
🔄 Efficient Autostart - Selective application launching with duplicate prevention

🛠️ Functionality

📱 Custom Dashboard - Integrated system controls and application launcher
🔒 Screen Locking - custom lockscreen using awesome UI component and lua-pam
🛡️ Security Features - physlock integration for absolute TTY protection during lock
🎵 Media Integration - Full playerctl support for multimedia control
🖥️ Multi-monitor Ready - Adaptive configuration for various display setups
⌨️ Intuitive Keybindings - Logical shortcuts for efficient workflow

🔧 Developer Experience

📦 Automated Installation - One-command setup with dependency management
📝 Comprehensive Documentation - Detailed configuration and customization guides
🎯 Easy Customization - Well-structured code with clear modification points

🧩 Core Components

Component	Purpose	Configuration Path	Description
AwesomeWM	Window Manager	`~/.config/awesome/`	Lua-based tiling WM with custom widgets
Rofi	Launcher	`~/.config/rofi/`	Application launcher with custom styling
Fastfetch	System Info	`~/.config/fastfetch/`	Modern system information display

📦 Package Dependencies

The configuration includes 32 carefully selected packages optimized for performance and functionality:

🏗️ Core System

awesome - High-performance AwesomeWM with Lua
srcom - Lightweight compositor for X11
wezterm - Customizable terminal emulator with GPU acceleration and Lua-based configuration

🎨 Theming & Appearance

ttf-jetbrains-mono-nerd - Programming font with icon support
noto-fonts - Comprehensive Unicode font coverage
oxygen5 / oxygen - Dark Qt themes
qt5ct / qt6ct - Qt configuration tools

🛠️ Utilities & Tools

rofi - Application launcher and window switcher
fastfetch - Modern system information display
playerctl - Media player control
brightnessctl - Backlight control
shutter - Screenshot tool

🔧 System Integration

bluez / bluez-utils - Bluetooth support
upower - Power management
lxqt-policykit - Authentication agent
xss-lock - Screen lock integration

Note: All packages are automatically installed via the install.sh script with proper AUR helper detection.

🚀 Installation

📋 System Requirements

OS: Arch Linux or Arch-based distribution (Manjaro, EndeavourOS, etc.)
Display: X11 (Wayland not supported)
Memory: Minimum 2GB RAM (4GB+ recommended)
Storage: ~500MB for all packages and configurations

⚡ Automated Installation

The recommended installation method using the provided script:

# Clone the repository
git clone https://github.com/nhktmdzhg/dotfiles-wm.git ~/dotfiles
cd ~/dotfiles

# Run the automated installer
chmod +x install.sh
./install.sh

What the installer does:

✅ System Check - Verifies Arch Linux and user permissions
💾 Backup Creation - Backs up existing configurations to ~/.dotfiles-backup-*
📦 AUR Helper - Installs paru if no AUR helper is detected
🔧 Package Installation - Installs all 32 required packages from pkgs.txt
📁 Configuration Deployment - Copies all dotfiles to appropriate locations
🔑 Permission Setup - Sets executable permissions for scripts
🔤 Font Cache - Updates system font cache

Manual Installation

Step-by-step manual process

# 1. Install AUR helper (if needed)
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin && makepkg -si

# 2. Install all packages
paru -S --needed $(cat ~/dotfiles/pkgs.txt | tr '\n' ' ')

# 3. Deploy configurations
cp -rf ~/dotfiles/home/username/. ~/

# 4. Set permissions
chmod +x ~/.config/awesome/lock.sh
chmod +x ~/.xinitrc

# 5. Update font cache
fc-cache -fv

🔄 Post-Installation

After installation, complete the setup:

Logout and select AwesomeWM from your display manager
Login to your new desktop environment
Add wallpapers to ~/wallpaper/ directory
Test keybindings using the reference below

🔐 Security Features

🛡️ Advanced Screen Locking

This configuration implements multiple layers of security for screen locking:

Primary Layer: Custom AwesomeWM Lockscreen

PAM Authentication - Uses lua-pam for secure password verification
Beautiful UI - Catppuccin Mocha themed lockscreen with wallpaper background
Hidden Password Input - No password length indicators for security
Interactive Indicator - Color-changing lock icon during typing

Secondary Layer: Physlock TTY Protection

Absolute TTY Blocking - Prevents all TTY access when screen is locked
Kernel-level Security - Bypasses user session entirely during lock
No Bypass Methods - Completely blocks Ctrl+Alt+F1-F12 and other TTY switching
System-wide Protection - Protects against physical access to terminals

Integration Architecture


┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ AwesomeWM	      │    │ physlock         │    │ PAM             │
│ Lockscreen      │───▶│ TTY Protection   │───▶│ Authentication  │
│ (lua-pam)       │    │ (kernel level)   │    │ (system auth)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Usage:

# Lock screen with both UI and TTY protection
~/.config/awesome/lock.sh

# Or use the keybinding: Super + L

Security Benefits:

✅ No TTY Access - Physical console access completely blocked
✅ PAM Integration - Uses system authentication framework
✅ Visual Feedback - Beautiful lockscreen with security indicators
✅ Session Protection - Prevents unauthorized session access
✅ Multi-layer Defense - UI lock + TTY lock + PAM auth

🔐 Security Features

🚀 Essential Shortcuts

Shortcut	Action	Application
`Super`	Application Launcher	Rofi
`Ctrl + Alt + T`	Terminal	Wezterm
`Super + E`	File Manager	Yazi
`Super + B`	Web Browser	Firefox
`Super + N`	Text Editor	Goneovim
`Super + Ctrl + N`	Toggle Notifications	naughty popup on/off
`Super + Esc`	Dashboard	Custom Dashboard
`Super + L`	Lock Screen	Custom Lockscreen

🪟 Window Management

Shortcut	Action	Description
`Super + F`	Fullscreen	Toggle fullscreen mode
`Super + X`	Maximize	Toggle window maximization
`Super + Z`	Minimize	Iconify current window
`Super + D`	Show Desktop	Hide/show all windows
`Alt + F4`	Close Window	Terminate active application
`Alt + Tab`	Window Switcher	Cycle through open windows
`Alt + Shift + Tab`	Reverse Switcher	Cycle windows in reverse
`Super + ←→↑↓`	Snap Window	Move window to screen edges

🎵 Media Controls

Shortcut	Action	Description
`XF86AudioPlay`	Play/Pause	Toggle media playback
`XF86AudioNext`	Next Track	Skip to next track
`XF86AudioPrev`	Previous Track	Skip to previous track
`XF86AudioRaiseVolume`	Volume Up	Increase system volume
`XF86AudioLowerVolume`	Volume Down	Decrease system volume
`XF86AudioMute`	Mute Toggle	Toggle audio mute

� Screenshots & System

Shortcut	Action	Tool
`Print`	Screenshot Toolbar	shutter
`Ctrl + Print`	Area Screenshot	shutter (region select)
`Ctrl + Shift + Esc`	System Monitor	bottom
`XF86MonBrightnessUp`	Brightness +	brightnessctl
`XF86MonBrightnessDown`	Brightness -	brightnessctl
`Super + Ctrl + R`	Reload WM	Restart AwesomeWM

🎨 Customization Guide

🌈 Color Themes

The configuration uses Catppuccin Mocha as the base theme. To customize colors:

-- Edit ~/.config/awesome/mocha.lua
return {
    name = 'mocha',
    base = { hex = '#1e1e2e' },      -- Background
    text = { hex = '#cdd6f4' },      -- Foreground text
    blue = { hex = '#89b4fa' },      -- Primary accent
    mauve = { hex = '#cba6f7' },     -- Secondary accent
    -- ... 26 total color definitions
}

🖼️ Wallpapers

Add your wallpapers to the ~/wallpaper/ directory. Then edit the config in ~/.config/awesome/config/wibar.lua to change the wallpaper:

# Add wallpapers
cp your-wallpaper.jpg ~/wallpaper/

-- Edit ~/.config/awesome/config/wibar.lua
screen.connect_signal('request::wallpaper', function(s)
	wallpaper.maximized(vars.wallpaper, s, true)
end)

⚙️ Default Applications

Modify default applications in ~/.config/awesome/config/keys.lua:

-- Example: Change default terminal
key({ ctrl, alt }, "t", function()
    spawn("alacritty")  -- Replace with your preferred terminal
end),

-- Example: Change default browser
key({ super }, "b", function()
    spawn("firefox")    -- Replace with your preferred browser
end),

🎛️ Dashboard Customization

The custom dashboard can be modified in ~/.config/awesome/config/dashboard.lua:

Add/remove quick actions
Modify power menu options
Customize media controls
Change layout and styling

🔧 AwesomeWM Configuration

Key configuration files and their purposes:

File	Purpose	Customization Options
`rc.lua`	Main entry point	Theme selection, module loading
`theme.lua`	Visual styling	Colors, fonts, spacing
`config/keys.lua`	Keybindings	Shortcuts, applications
`config/rules.lua`	Window rules	Placement, properties
`config/widgets.lua`	Status bar widgets	System monitoring, layout

🔗 Recommended Companions

Enhance your desktop experience with these complementary configurations:

Component	Description	Repository
🔧 Neovim	Modern Vim-based editor with LSP	nhktmdzhg/nvim

🐛 Troubleshooting

🔧 Common Issues

Installation Problems

AUR Helper Installation Fails

# Manual paru installation
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin && makepkg -si --noconfirm

Package Installation Errors

# Update system first
sudo pacman -Syu
# Clear package cache
paru -Sc
# Retry installation
paru -S --needed $(cat ~/dotfiles/pkgs.txt | tr '\n' ' ')

Runtime Issues

Font Rendering Problems

# Rebuild font cache
fc-cache -fv
# Verify JetBrains Mono installation
fc-list | grep -i jetbrains

AwesomeWM Won't Start

# Check configuration syntax
awesome -k ~/.config/awesome/rc.lua
# View error logs
journalctl -u display-manager -f

Permission Fixes

# Fix script permissions
chmod +x ~/.config/awesome/lock.sh
chmod +x ~/.xinitrc

# Fix ownership issues
sudo chown -R $USER:$USER ~/.config/

🤝 Contributing

We welcome contributions to improve this AwesomeWM configuration! Here's how you can help:

🐛 Bug Reports

Use the issue tracker to report bugs
Include system information (OS, AwesomeWM version, etc.)
Provide steps to reproduce the issue

✨ Feature Requests

Suggest new features or improvements
Explain the use case and expected behavior
Consider submitting a pull request if you can implement it

🔧 Pull Requests

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Test your changes thoroughly
Commit with clear messages: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Open a Pull Request with detailed description

📄 License

This project is licensed under the MIT License - see the LICENSE file for complete details.

MIT License - Free to use, modify, and distribute

🙏 Acknowledgments

Special thanks to the amazing open-source community:

AwesomeWM - The incredibly flexible and powerful window manager
Catppuccin - Beautiful, soothing pastel color palette
BeautyLine - Elegant and consistent icon theme
Arch Linux - The simple, lightweight distribution
Community Contributors - Everyone who tested, reported issues, and suggested improvements

🌟 Show Your Support

If this configuration helped you create an amazing desktop experience, please consider:

Made with 💙 by ミツキナノカ

Crafted for developers, by developers

Name		Name	Last commit message	Last commit date
Latest commit History 144 Commits
etc/pam.d		etc/pam.d
home/username		home/username
meo		meo
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
pkgs.txt		pkgs.txt

Folders and files

Latest commit

History

Repository files navigation

🌟 AwesomeWM Dotfiles • ミツキナノカ's Desktop Environment

📸 Screenshots

✨ Key Features

🎨 Visual Design

⚡ Performance & Efficiency

🛠️ Functionality

🔧 Developer Experience

🧩 Core Components

📦 Package Dependencies

🏗️ Core System

🎨 Theming & Appearance

🛠️ Utilities & Tools

🔧 System Integration

🚀 Installation

📋 System Requirements

⚡ Automated Installation

Manual Installation

🔄 Post-Installation

🔐 Security Features

🛡️ Advanced Screen Locking

Primary Layer: Custom AwesomeWM Lockscreen

Secondary Layer: Physlock TTY Protection

Integration Architecture

🔐 Security Features

🚀 Essential Shortcuts

🪟 Window Management

🎵 Media Controls

� Screenshots & System

🎨 Customization Guide

🌈 Color Themes

🖼️ Wallpapers

⚙️ Default Applications

🎛️ Dashboard Customization

🔧 AwesomeWM Configuration

🔗 Recommended Companions

🐛 Troubleshooting

🔧 Common Issues

🤝 Contributing

🐛 Bug Reports

✨ Feature Requests

🔧 Pull Requests

📄 License

🙏 Acknowledgments

🌟 Show Your Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages