public/omnixy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d45b690a1a7e2e7bc7753fbc1d6cbc879de90f0b
omnixy/docs/INSTALLATION.md
theArctesian d8947e67b7 documentation
2025-09-25 07:50:48 -07:00

9.4 KiB
Raw Blame History

OmniXY Installation Guide

This guide covers all methods of installing OmniXY on your NixOS system, from automated installation to manual configuration.

Prerequisites

System Requirements

  • Operating System: NixOS 24.05 or newer
  • RAM: 8GB minimum (16GB+ recommended for development)
  • Storage: 40GB free space (for Nix store and applications)
  • Boot: UEFI system (for systemd-boot configuration)
  • Network: Stable internet connection for package downloads

Pre-Installation Checklist

# Verify NixOS installation
cat /etc/NIXOS

# Check available space
df -h /

# Verify internet connectivity
ping -c 3 github.com

# Check user permissions
groups $USER | grep -q wheel && echo "User has sudo access"

Installation Methods

Method 1: Bootstrap Installation (Recommended)

The fastest way to install OmniXY on a fresh NixOS system:

# Download and run bootstrap installer
curl -fsSL https://raw.githubusercontent.com/thearctesian/omnixy/main/boot.sh | bash

What this does:

  1. Verifies NixOS installation
  2. Downloads OmniXY repository
  3. Runs the interactive installer
  4. Guides you through configuration

Advantages:

  • Single command installation
  • Always uses latest version
  • No local repository needed
  • Automatic dependency handling

Method 2: Interactive Installation

For users who want control over the installation process:

# Clone the repository
git clone https://github.com/thearctesian/omnixy
cd omnixy

# Run interactive installer
./install.sh

Features:

  • Beautiful terminal interface with Tokyo Night colors
  • Step-by-step guidance
  • Theme selection with previews
  • Optional features configuration
  • Progress indication
  • Automatic backup creation

Installation Steps:

  1. System Verification: Checks NixOS and permissions
  2. Configuration Backup: Saves existing /etc/nixos
  3. File Installation: Copies OmniXY configuration
  4. User Setup: Configure username and home directory
  5. Theme Selection: Choose from 11 available themes
  6. Feature Configuration: Enable optional features
  7. System Build: Build and switch to new configuration

Method 3: Simple Installation (Unix Philosophy)

For automation and scripting:

# Clone repository
git clone https://github.com/thearctesian/omnixy
cd omnixy

# Run simple installer with options
./install-simple.sh --user alice --theme gruvbox --quiet

Command Options:

  • --user USERNAME: Set username (default: prompt)
  • --theme THEME: Select theme (default: tokyo-night)
  • --quiet, -q: Minimal output
  • --dry-run, -n: Test without applying changes
  • --help, -h: Show help

Environment Variables:

  • OMNIXY_USER: Default username
  • OMNIXY_THEME: Default theme
  • OMNIXY_QUIET=1: Enable quiet mode

Examples:

# Fully automated installation
OMNIXY_USER=developer OMNIXY_THEME=tokyo-night ./install-simple.sh --quiet

# Test installation without applying
./install-simple.sh --user testuser --dry-run

# Interactive theme selection
./install-simple.sh --user alice

Method 4: Manual Flake Installation

For advanced users who want direct control:

# Direct flake installation (replaces entire system)
sudo nixos-rebuild switch --flake github:thearctesian/omnixy#omnixy

# Or with local repository
git clone https://github.com/thearctesian/omnixy
cd omnixy
sudo nixos-rebuild switch --flake .#omnixy

Important Notes:

  • Requires manual user configuration editing
  • No automatic backup
  • Assumes advanced Nix knowledge
  • May overwrite existing configuration

Step-by-Step Installation Process

1. Pre-Installation Setup

# Update NixOS channel (optional)
sudo nix-channel --update

# Ensure git is available
nix-shell -p git --run "git --version"

# Create backup directory (optional)
mkdir -p ~/nixos-backups

2. Repository Setup

# Clone to home directory
cd ~
git clone https://github.com/thearctesian/omnixy
cd omnixy

# Verify repository integrity
ls -la  # Should see flake.nix, configuration.nix, etc.
nix flake check  # Verify flake is valid

3. Configuration Customization (Optional)

Before installation, you can customize:

# Edit user configuration
vim home.nix  # Modify user packages and settings

# Modify system packages
vim modules/packages.nix  # Add/remove system packages

# Hardware-specific changes
vim hardware-configuration.nix  # Update for your hardware

4. Installation Execution

Choose your preferred installer and run it:

# Interactive (recommended for first-time users)
./install.sh

# Simple (for automation)
./install-simple.sh --user $USER --theme tokyo-night

# Manual (for experts)
sudo nixos-rebuild switch --flake .#omnixy

5. Post-Installation Configuration

After installation completes:

# Verify installation
omnixy info

# Check available commands
omnixy help

# Test theme switching
omnixy theme list
omnixy theme set nord

# Verify system health
systemctl status
journalctl -b | grep -i error

Customization During Installation

Theme Selection

Available themes during installation:

  1. tokyo-night (default) - Dark with vibrant blues
  2. catppuccin - Warm, soothing pastels
  3. gruvbox - Retro earth tones
  4. nord - Cool Arctic colors
  5. everforest - Natural greens
  6. rose-pine - Elegant pinks
  7. kanagawa - Japanese-inspired
  8. catppuccin-latte - Light variant
  9. matte-black - Minimal black/white
  10. osaka-jade - Jade greens
  11. ristretto - Coffee browns

Feature Configuration

Optional features you can enable:

Security Features:

  • Fingerprint authentication
  • FIDO2 security keys
  • Two-factor authentication

Development Features:

  • Docker/Podman support
  • Development databases
  • Additional programming languages

Gaming Features:

  • Steam integration
  • Wine compatibility
  • Gaming optimizations

Multimedia Features:

  • Video editing tools
  • Audio production software
  • Graphics applications

Hardware Configuration

The installer automatically detects and configures:

  • GPU drivers (Intel, AMD, NVIDIA)
  • Audio hardware (PipeWire setup)
  • Network interfaces
  • Bluetooth devices
  • Input devices (touchpad, etc.)

Troubleshooting Installation

Common Issues

"Not running on NixOS" Error:

# Verify NixOS installation
ls /etc/NIXOS
nixos-version

Permission Denied Errors:

# Ensure user is in wheel group
groups $USER | grep wheel

# Add user to wheel group if needed
sudo usermod -aG wheel $USER

Network/Download Issues:

# Test internet connectivity
curl -I https://github.com
ping -c 3 cache.nixos.org

# Check DNS resolution
nslookup github.com

Insufficient Space:

# Check available space
df -h /
du -sh /nix/store

# Clean up if needed
nix-collect-garbage -d

Build Failures

Flake Evaluation Errors:

# Check flake syntax
nix flake check --show-trace

# Debug with verbose output
nixos-rebuild build --flake .#omnixy --show-trace

Package Build Failures:

# Check for specific package errors
journalctl -u nix-daemon | grep -i error

# Try building individual packages
nix build .#omnixy-scripts

Out of Memory During Build:

# Check memory usage
free -h
htop

# Enable swap if needed
sudo swapon -a

# Build with fewer jobs
nixos-rebuild build --flake .#omnixy --max-jobs 1

Recovery Options

Rollback to Previous Configuration:

# List available generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Rollback to previous generation
sudo nixos-rebuild switch --rollback

Restore from Backup:

# If backup was created during installation
sudo cp -r /etc/nixos.backup.TIMESTAMP/* /etc/nixos/
sudo nixos-rebuild switch

Boot from Rescue Environment: If the system fails to boot:

  1. Boot from NixOS live USB
  2. Mount the system
  3. Restore backup or rollback
  4. Rebuild system

Verification and Testing

Post-Installation Checks

# System information
omnixy info

# Theme verification
omnixy theme get

# Package verification
which alacritty hyprland waybar

# Service status
systemctl --user status hyprland
systemctl status NetworkManager

Functional Testing

# Test theme switching
omnixy theme set gruvbox
omnixy theme set tokyo-night

# Test utilities
omnixy-screenshot --help
omnixy search firefox

# Test development environments
nix develop .#rust --command rustc --version
nix develop .#python --command python --version

Performance Verification

# Check boot time
systemd-analyze

# Check memory usage
free -h
ps aux --sort=-%mem | head

# Check disk usage
df -h
du -sh /nix/store

Next Steps After Installation

Essential Configuration

  1. Set up Git: Configure name and email
  2. Configure Shell: Customize zsh/bash settings
  3. Install Additional Software: Add personal packages
  4. Set up Development: Configure programming environments

System Maintenance

# Regular updates
omnixy update

# Regular cleanup
omnixy clean

# Monitor system health
omnixy info

Customization

  1. Explore Themes: Try different color schemes
  2. Customize Keybindings: Modify Hyprland shortcuts
  3. Add Packages: Edit configuration files
  4. Create Backups: Regular system backups

This installation guide provides multiple paths to get OmniXY running on your system, accommodating different user preferences and technical backgrounds.