Flouda Vault

9 min read

Overview

This automated setup utility transforms a fresh Arch Linux installation into a fully configured Hyprland desktop environment. The script handles everything from package installation to dotfile deployment, creating a modern Wayland-based desktop that’s ready for daily use.

The setup includes a complete Hyprland configuration with Waybar, custom themes, essential applications, and a sophisticated “FOSS” (First-time login, One-shot, Self-destroying Setup) system that handles post-installation configuration automatically.

What Gets Installed

Core Desktop Environment

  • Hyprland: Modern Wayland compositor with tiling window management
  • Waybar: Highly customizable status bar with system information
  • Wofi: Application launcher and menu system
  • Greetd + Regreet: Modern display manager with clean login interface
  • Kitty: GPU-accelerated terminal emulator
  • UWSM: User session management for Wayland

System Components

  • Pipewire Audio Stack: Complete audio solution with ALSA, PulseAudio, and JACK compatibility
  • Polkit: Policy framework for privileged operations
  • XDG Desktop Portal: Integration for desktop environment features
  • SwayNC: Notification daemon with modern interface

Applications and Tools

  • File Management: Nemo file manager with archive support
  • Text Editing: GNOME Text Editor and Neovim
  • Media: Eye of GNOME image viewer, audio controls
  • Screenshot Tools: Grim, Slurp, and Grimblast for screen capture
  • Productivity: Obsidian note-taking application
  • Browser: Zen Browser for web browsing

Development and Terminal

  • Shell: Zsh with Oh My Zsh framework
  • Terminal Tools: tmux, ranger, fzf, zoxide
  • Development: Node.js, npm for web development
  • Text Processing: Tesseract OCR with English language data

Themes and Appearance

  • GTK Theme: BetterGruvbox with consistent styling
  • Icons: Papirus icon theme with folder customization
  • Cursors: Bibata cursor theme
  • Fonts: Comprehensive font collection including Nerd Fonts, Fira Code, and system fonts

Prerequisites

System Requirements

  • Fresh Arch Linux installation
  • User account with sudo privileges
  • Internet connection for package downloads
  • At least 4GB of free disk space

Important Notes

  • Do not run as root: The script includes safety checks and will exit if run with root privileges
  • Sudo access required: Your user must be in the sudoers group
  • Pacman required: Script is specifically designed for Arch Linux systems

Installation Methods

Quick Installation

curl -fsSL https://vault.flouda.io/scripts/setup-desktop | bash

Manual Download and Execution

wget https://vault.flouda.io/scripts/setup-desktop
chmod +x setup-desktop
./setup-desktop

What the Script Does

Phase 1: System Preparation

  1. Security Checks: Validates user permissions and system compatibility
  2. Package Manager Setup: Installs yay AUR helper if not present
  3. System Update: Performs full system upgrade before installation
  4. Temporary Sudo Configuration: Sets passwordless sudo for installation duration

Phase 2: Package Installation

The script installs over 50 packages including:

  • Core Hyprland ecosystem components
  • Audio and multimedia frameworks
  • Development tools and applications
  • Fonts and theming components
  • Essential desktop applications

Phase 3: Shell Configuration

  • Oh My Zsh Installation: Modern Zsh framework with plugins
  • Plugin Setup: Autosuggestions and syntax highlighting
  • Default Shell: Changes default shell to Zsh
  • Custom Aliases: Installs productivity-enhancing command aliases

Phase 4: Dotfiles Deployment

  • Repository Cloning: Downloads latest dotfiles configuration
  • System Configuration: Places display manager and background files
  • User Configuration: Deploys personal configuration files
  • Custom Aliases: Installs shell productivity enhancements

Phase 5: FOSS Setup

The “First-time login, One-shot, Self-destroying Setup” system:

  • Downloads post-installation configuration scripts
  • Creates systemd user service for first-boot execution
  • Handles GUI-specific settings that require an active session
  • Self-destructs after successful completion

Phase 6: System Finalization

  • Service Activation: Enables display manager service
  • Cleanup: Removes temporary sudo configuration
  • Automatic Reboot: Restarts system to apply all changes

FOSS (First-time login, One-shot, Self-destroying Setup)

Purpose and Design

Traditional Linux desktop setup scripts face a fundamental limitation: many GUI applications and desktop environment settings cannot be configured from the command line during system installation. These settings require an active desktop session to function properly.

FOSS solves this elegantly by:

  • Running configuration commands after the first desktop login
  • Executing only once per user account
  • Automatically removing itself after successful completion
  • Handling GUI-specific configurations that traditional scripts cannot

How FOSS Works

  1. Service Creation: Creates a systemd user service that runs on login
  2. First-Run Detection: Uses a marker file to ensure single execution
  3. Configuration Execution: Runs GUI-specific setup commands
  4. Self-Destruction: Removes service and scripts after completion
  5. Clean State: Leaves no trace after successful configuration

What FOSS Configures

  • Desktop environment appearance settings
  • Application-specific configurations requiring GUI context
  • Theme applications and customizations
  • Any settings that require an active Wayland/X11 session

Customization and Modification

Modifying Package Lists

To customize installed packages, edit the install_packages() function:

# Add packages to the yay command
yay -Syyu --noconfirm --needed [your-packages-here]

Dotfiles Customization

The script uses dotfiles from the GitLab repository. To use your own:

  1. Fork or create your own dotfiles repository
  2. Modify the place_dotfiles() function to point to your repository
  3. Ensure your dotfiles structure matches the expected layout

Theme Modifications

Current themes can be changed by:

  • Modifying package selection in install_packages()
  • Updating dotfiles to reference different themes
  • Adjusting FOSS configuration for theme-specific settings

Troubleshooting

Common Issues

Script Exits with Permission Error

  • Ensure your user has sudo privileges
  • Do not run the script as root
  • Check if user is in the wheel group

Package Installation Failures

  • Verify internet connection
  • Update system keyring: sudo pacman -Sy archlinux-keyring
  • Clear package cache: sudo pacman -Scc

Yay Installation Problems

  • Install base-devel group manually: sudo pacman -S base-devel
  • Check available disk space in /tmp
  • Ensure git is installed: sudo pacman -S git

Display Manager Issues

  • Check greetd service status: systemctl status greetd
  • Verify configuration files in /etc/greetd/
  • Check system logs: journalctl -u greetd

FOSS Service Problems

  • Check service status: systemctl --user status foss
  • View service logs: journalctl --user -u foss
  • Manually trigger: systemctl --user start foss

Recovery Options

Incomplete Installation

# Clean package cache
sudo pacman -Scc
 
# Remove failed AUR builds
rm -rf ~/.cache/yay
 
# Restart installation
curl -fsSL https://vault.flouda.io/scripts/setup-desktop | bash

Dotfiles Issues

# Backup current config
cp -r ~/.config ~/.config.backup
 
# Re-download dotfiles
git clone https://gitlab.com/flouda/dotfiles /tmp/dotfiles-recovery
cp -r /tmp/dotfiles-recovery/user-home/.config/* ~/.config/

Display Manager Recovery

# Fallback to TTY login
sudo systemctl disable greetd
sudo systemctl enable getty@tty1
 
# Reconfigure after troubleshooting
sudo systemctl enable greetd
sudo systemctl start greetd

Security Considerations

Temporary Sudo Configuration

The script temporarily grants passwordless sudo access for smooth installation. This configuration:

  • Is automatically removed after completion
  • Uses a trap to ensure cleanup even if script fails
  • Is limited to the installation duration only
  • Does not persist beyond the script execution

External Dependencies

The script downloads content from:

  • Official Arch repositories (via pacman)
  • Arch User Repository (via yay)
  • GitLab dotfiles repository
  • Oh My Zsh installation script

All downloads use HTTPS connections and official sources.

Best Practices

  • Review the script content before execution
  • Run on a test system before production use
  • Backup important data before installation
  • Understand what packages and configurations are being installed

Advanced Configuration

Custom Font Installation

To add additional fonts, modify the font packages in install_packages():

# Add to the package list
ttf-your-custom-font noto-fonts-extra ttf-liberation

Additional AUR Packages

Extend functionality by adding AUR packages:

# Example additions
visual-studio-code-bin discord slack-desktop

Development Environment Extensions

For development workflows, consider adding:

# Development tools
docker docker-compose git-lfs github-cli

Integration with Other Systems

Dotfiles Management

The setup integrates with a comprehensive dotfiles management system. Related utilities include:

System Administration

For ongoing system management, see:

Script Architecture

Function Overview

  • guard_pass(): Security and compatibility validation
  • ensure_yay(): AUR helper installation and configuration
  • install_packages(): Complete package installation workflow
  • set_nopasswd()/rm_nopasswd(): Temporary sudo configuration
  • setup_oh_my_zsh(): Shell framework and plugin installation
  • place_dotfiles(): Configuration file deployment
  • foss_setup(): Post-installation service configuration
  • reboot_prompt(): System restart with countdown

Error Handling

The script includes:

  • Exit on error (set -e)
  • Cleanup traps for temporary configurations
  • Command existence checks
  • Permission validation
  • Network connectivity assumptions

Logging and Output

  • Color-coded status messages
  • Progress indicators for long operations
  • Clear error reporting
  • Installation countdown timers

Performance Considerations

Installation Time

Typical installation takes 15-30 minutes depending on:

  • Internet connection speed
  • System hardware specifications
  • Package compilation requirements
  • AUR package build times

Resource Usage

During installation:

  • Download size: ~2-3GB of packages
  • Temporary storage: ~1GB in /tmp
  • Memory usage: Standard for package compilation
  • CPU usage: Intensive during AUR builds

Optimization Tips

  • Use fast internet connection for initial installation
  • Ensure adequate free disk space (4GB minimum)
  • Close unnecessary applications during installation
  • Consider SSD storage for better compilation performance

References and Resources

Official Documentation

Community Resources

Questions Answered in This Document

Q: What is the Hyprland desktop setup script and what does it install? A: It’s an automated installation script that transforms a fresh Arch Linux system into a complete Hyprland Wayland desktop environment with over 50 packages including the compositor, status bar, applications, themes, and development tools.

Q: Can I run this script as root or do I need special permissions? A: Do not run as root. The script requires a regular user account with sudo privileges and includes safety checks to prevent root execution.

Q: What is FOSS and why is it needed for desktop setup? A: FOSS (First-time login, One-shot, Self-destroying Setup) is a systemd service that handles GUI-specific configurations after the first desktop login, solving the limitation that many desktop settings cannot be configured from command line during installation.

Q: How long does the installation take and how much disk space is required? A: Installation typically takes 15-30 minutes depending on internet speed and hardware, requiring at least 4GB of free disk space and downloading approximately 2-3GB of packages.

Q: What happens if the installation script fails or is interrupted? A: The script includes error handling and cleanup procedures, automatically removing temporary sudo configurations even if interrupted, with recovery options available for common failure scenarios.

Q: Can I customize which packages get installed or use my own dotfiles? A: Yes, you can modify the install_packages() function to change package selection and update the place_dotfiles() function to use your own dotfiles repository.

Q: What desktop applications and tools are included in the setup? A: The setup includes Kitty terminal, Nemo file manager, GNOME Text Editor, Neovim, Obsidian, Zen Browser, development tools (Node.js, tmux, ranger), and complete multimedia support with Pipewire.

Q: How do I troubleshoot common installation issues like package failures or display manager problems? A: Common solutions include checking sudo privileges, updating system keyring, clearing package cache, verifying internet connection, and checking service status with systemctl and journalctl commands.

Q: Is the installation secure and what external sources does it download from? A: The script uses HTTPS connections to download from official Arch repositories, AUR, GitLab dotfiles repository, and Oh My Zsh, with temporary sudo access automatically cleaned up after installation.

Q: What themes and visual customizations are applied during setup? A: The setup applies BetterGruvbox GTK theme, Papirus icons, Bibata cursors, comprehensive Nerd Fonts collection, and custom Hyprland configurations for a cohesive modern desktop appearance.

Graph View

Backlinks