dotfiles/INSTALL.md

# Installation Guide

This guide provides detailed installation instructions for the Hyprland dotfiles configuration.

## Prerequisites

### System Requirements
- **Operating System**: Arch Linux (primary support)
- **Display Server**: Wayland
- **Memory**: Minimum 4GB RAM (8GB recommended)
- **Storage**: At least 2GB free space
- **GPU**: Any GPU with Vulkan support (Intel/AMD/NVIDIA)

### Required Knowledge
- Basic Linux command line usage
- Understanding of symbolic links
- Familiarity with package managers (pacman)

## Installation Methods

### Method 1: Automated Installation (Recommended)

This is the fastest way to get up and running:

```bash
# Clone the repository
cd ~/
git clone https://github.com/TolaMironcenko/hyprland_dotfiles.git dotfiles
cd dotfiles

# Make the script executable
chmod +x install_scripts/install.sh

# Run the installation
./install_scripts/install.sh
```

**What this does:**
- Creates symbolic links for all configuration files
- Backs up existing configurations (if any)
- Sets up proper directory structure
- Installs custom scripts to `~/dotfiles/bin`

### Method 2: Manual Installation

For users who want full control over the installation process:

#### Step 1: Clone Repository
```bash
cd ~/
git clone https://github.com/TolaMironcenko/hyprland_dotfiles.git dotfiles
cd dotfiles
```

#### Step 2: Backup Existing Configurations
```bash
# Create backup directory
mkdir -p ~/config_backup/$(date +%Y%m%d_%H%M%S)

# Backup existing configs
[ -d ~/.config/hypr ] && mv ~/.config/hypr ~/config_backup/$(date +%Y%m%d_%H%M%S)/
[ -d ~/.config/waybar ] && mv ~/.config/waybar ~/config_backup/$(date +%Y%m%d_%H%M%S)/
[ -d ~/.config/kitty ] && mv ~/.config/kitty ~/config_backup/$(date +%Y%m%d_%H%M%S)/
[ -d ~/.config/mako ] && mv ~/.config/mako ~/config_backup/$(date +%Y%m%d_%H%M%S)/
[ -f ~/.vimrc ] && mv ~/.vimrc ~/config_backup/$(date +%Y%m%d_%H%M%S)/
```

#### Step 3: Create Symbolic Links
```bash
# Essential configurations
ln -sf ~/dotfiles/hypr ~/.config/hypr
ln -sf ~/dotfiles/waybar ~/.config/waybar
ln -sf ~/dotfiles/kitty ~/.config/kitty
ln -sf ~/dotfiles/mako ~/.config/mako
ln -sf ~/dotfiles/ranger ~/.config/ranger
ln -sf ~/dotfiles/fastfetch ~/.config/fastfetch
ln -sf ~/dotfiles/rofi ~/.config/rofi

# Shell and system configs
ln -sf ~/dotfiles/vimrc ~/.vimrc
ln -sf ~/dotfiles/tmux.conf ~/.tmux.conf
ln -sf ~/dotfiles/gitconfig ~/.gitconfig

# Optional configurations
ln -sf ~/dotfiles/greenclip/greenclip.toml ~/.config/greenclip.toml
ln -sf ~/dotfiles/rofi/emoji/rofimoji.rc ~/.config/rofimoji.rc
```

#### Step 4: Set Up Custom Scripts
```bash
# Add dotfiles bin to PATH (if not already done)
echo 'export PATH=$PATH:~/dotfiles/bin' >> ~/.bashrc
# or for zsh users:
echo 'export PATH=$PATH:~/dotfiles/bin' >> ~/.zshrc

# Make scripts executable
chmod +x ~/dotfiles/bin/*
chmod +x ~/dotfiles/hypr/bin/*
```

### Method 3: Docker-based Testing

For testing the configuration without affecting your system:

```bash
# Build the test environment
docker build -t hyprland-dotfiles .

# Run the test environment
docker run -it hyprland-dotfiles
```

## Package Installation

### Essential Packages

Install these packages before using the configuration:

```bash
# Core Hyprland packages
sudo pacman -S hyprland waybar rofi kitty mako

# System utilities
sudo pacman -S fastfetch ranger vim git tmux

# Audio and media
sudo pacman -S pulseaudio pulseaudio-alsa pamixer

# Fonts (important for proper display)
sudo pacman -S ttf-fira-code noto-fonts noto-fonts-emoji

# Additional tools
sudo pacman -S grim slurp wl-clipboard xdg-utils
```

### AUR Packages

Some packages are available in the AUR:

```bash
# Using yay AUR helper
yay -S greenclip hyprlock hyprpaper

# Or using paru
paru -S greenclip hyprlock hyprpaper
```

### Optional Packages

These packages enhance the experience but aren't required:

```bash
# Notification alternatives
sudo pacman -S swaync dunst

# Terminal alternatives
sudo pacman -S alacritty

# System monitoring
sudo pacman -S htop btop neofetch cava

# Display management
sudo pacman -S ly picom

# Development tools
sudo pacman -S code firefox thunderbird
```

## Post-Installation Setup

### 1. Shell Configuration

Add the shell configuration to your shell's RC file:

```bash
# For bash users
echo 'source ~/dotfiles/shell/source.sh' >> ~/.bashrc

# For zsh users
echo 'source ~/dotfiles/shell/source.sh' >> ~/.zshrc

# Reload your shell
source ~/.bashrc  # or ~/.zshrc
```

### 2. Environment Variables

Set up environment variables for optimal Wayland experience:

```bash
# Add to ~/.pam_environment or ~/.profile
export XDG_CURRENT_DESKTOP=Hyprland
export XDG_SESSION_DESKTOP=Hyprland
export XDG_SESSION_TYPE=wayland
export MOZ_ENABLE_WAYLAND=1
export QT_QPA_PLATFORM=wayland
export QT_WAYLAND_DISABLE_WINDOWDECORATION=1
export GDK_BACKEND=wayland
```

### 3. Display Manager Setup

If using a display manager, configure it to start Hyprland:

#### For GDM/LightDM
Create a desktop entry:
```bash
sudo tee /usr/share/wayland-sessions/hyprland.desktop > /dev/null <<EOF
[Desktop Entry]
Name=Hyprland
Comment=An intelligent dynamic tiling Wayland compositor
Exec=Hyprland
Type=Application
EOF
```

#### For SDDM
```bash
sudo systemctl enable sddm
```

### 4. Auto-start Services

Enable necessary services:

```bash
# Audio service
systemctl --user enable pulseaudio

# Clipboard manager
systemctl --user enable greenclip

# Notification daemon
systemctl --user enable mako
```

## Customization

### 1. Monitor Configuration

Edit `~/dotfiles/hypr/monitors.conf` to match your setup:

```bash
# Example for single monitor
monitor=,preferred,auto,1

# Example for dual monitors
monitor=DP-1,1920x1080@60,0x0,1
monitor=HDMI-A-1,1920x1080@60,1920x0,1
```

### 2. Keyboard Layout

Edit `~/dotfiles/hypr/keyboard.conf`:

```bash
input {
    kb_layout = us
    kb_variant = 
    kb_model =
    kb_options =
    kb_rules =
}
```

### 3. Startup Applications

Edit `~/dotfiles/hypr/startup.conf` to add your applications:

```bash
exec-once = discord
exec-once = firefox
exec-once = spotify
```

### 4. Window Rules

Customize window behavior in `~/dotfiles/hypr/windowrules.conf`:

```bash
# Example window rules
windowrule = float, ^(pavucontrol)$
windowrule = size 800 600, ^(pavucontrol)$
windowrule = opacity 0.8, ^(kitty)$
```

## Troubleshooting

### Common Issues

#### 1. Hyprland Won't Start

**Check GPU drivers:**
```bash
lspci -k | grep -A 2 -E "(VGA|3D)"
```

**For NVIDIA users:**
```bash
# Install proprietary drivers
sudo pacman -S nvidia nvidia-utils

# Add to kernel parameters
sudo vim /etc/default/grub
# Add: nvidia-drm.modeset=1
sudo grub-mkconfig -o /boot/grub/grub.cfg
```

#### 2. Waybar Not Showing

**Check if running:**
```bash
pgrep waybar
```

**Restart Waybar:**
```bash
killall waybar
waybar &
```

**Check configuration:**
```bash
waybar -c ~/.config/waybar/config -s ~/.config/waybar/style.css
```

#### 3. Audio Issues

**Check PulseAudio:**
```bash
pulseaudio --check
pactl info
```

**Restart audio system:**
```bash
pulseaudio -k
pulseaudio --start
```

#### 4. Rofi Not Working

**Test Rofi:**
```bash
rofi -show drun
```

**Check theme:**
```bash
rofi-theme-selector
```

#### 5. Fonts Not Displaying Correctly

**Install additional fonts:**
```bash
sudo pacman -S ttf-liberation ttf-dejavu
```

**Rebuild font cache:**
```bash
fc-cache -fv
```

### Log Files

Check these locations for debugging:

- **Hyprland**: `~/.local/share/hyprland/hyprland.log`
- **Waybar**: `journalctl --user -u waybar`
- **System**: `journalctl -xe`

### Performance Issues

#### 1. High CPU Usage

**Check running processes:**
```bash
htop
```

**Optimize Hyprland:**
```bash
# In hyprland.conf
misc {
    vfr = true
    vrr = 1
}
```

#### 2. Memory Usage

**Monitor memory:**
```bash
free -h
watch -n 1 'cat /proc/meminfo | grep -E "MemTotal|MemFree|MemAvailable"'
```

## Updating

### Update Dotfiles

```bash
cd ~/dotfiles
git pull origin main
```

### Update System

```bash
# Update packages
sudo pacman -Syu

# Update AUR packages
yay -Syu  # or paru -Syu
```

### Backup Before Updates

```bash
# Create backup
tar -czf ~/dotfiles_backup_$(date +%Y%m%d).tar.gz ~/.config/hypr ~/.config/waybar ~/.config/kitty

# Or use the backup script
~/dotfiles/bin/backup_configs.sh
```

## Uninstallation

### Remove Configurations

```bash
# Remove symbolic links
rm ~/.config/hypr ~/.config/waybar ~/.config/kitty ~/.config/mako
rm ~/.vimrc ~/.tmux.conf ~/.gitconfig

# Remove from PATH
# Edit ~/.bashrc or ~/.zshrc and remove the PATH addition
```

### Remove Packages

```bash
# Remove main packages
sudo pacman -R hyprland waybar rofi kitty mako

# Remove AUR packages
yay -R greenclip hyprlock hyprpaper
```

### Restore Backups

```bash
# If you created backups
mv ~/config_backup/[timestamp]/* ~/.config/
```

## Getting Help

### Community Support

- **Discord**: [Hyprland Discord](https://discord.gg/hyprland)
- **Reddit**: r/hyprland
- **GitHub Issues**: [Project Issues](https://github.com/TolaMironcenko/hyprland_dotfiles/issues)

### Documentation

- **Hyprland Wiki**: [hyprland.org](https://hyprland.org)
- **Waybar Documentation**: [Waybar GitHub](https://github.com/Alexays/Waybar)
- **Arch Wiki**: [Hyprland - ArchWiki](https://wiki.archlinux.org/title/Hyprland)

### Reporting Issues

When reporting issues, please include:

1. **System Information**:
   ```bash
   uname -a
   lscpu | grep "Model name"
   lspci | grep VGA
   ```

2. **Package Versions**:
   ```bash
   pacman -Q hyprland waybar rofi kitty
   ```

3. **Log Files**:
   ```bash
   tail -50 ~/.local/share/hyprland/hyprland.log
   ```

4. **Configuration Files**:
   - Your modified configuration files
   - Any custom scripts or modifications

---

**Note**: This installation guide is primarily for Arch Linux. For other distributions, package names and installation methods may differ.