documentation
This commit is contained in:
theArctesian
216
docs/ARCHITECTURE.md
Normal file
216
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# OmniXY Architecture
|
||||
|
||||
## Overview
|
||||
OmniXY is built on a layered architecture that combines NixOS's declarative system configuration with modern desktop tools and development environments.
|
||||
|
||||
## System Layers
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ User Interface │
|
||||
│ Hyprland + Waybar + Applications │
|
||||
├─────────────────────────────────────────┤
|
||||
│ Desktop Environment │
|
||||
│ Theme System + Window Management │
|
||||
├─────────────────────────────────────────┤
|
||||
│ OmniXY Configuration │
|
||||
│ Modules + Scripts + Packages │
|
||||
├─────────────────────────────────────────┤
|
||||
│ Home Manager Layer │
|
||||
│ User Environment & Dotfiles │
|
||||
├─────────────────────────────────────────┤
|
||||
│ NixOS System │
|
||||
│ Package Management + Services │
|
||||
├─────────────────────────────────────────┤
|
||||
│ Linux Kernel │
|
||||
│ Hardware Abstraction │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Nix Flake System (`flake.nix`)
|
||||
The foundation that defines all system inputs and outputs:
|
||||
- **Inputs**: External dependencies (nixpkgs, home-manager, hyprland)
|
||||
- **Outputs**: System configurations, packages, development shells, apps
|
||||
- **Lock File**: Ensures reproducible builds across machines
|
||||
|
||||
### 2. System Configuration (`configuration.nix`)
|
||||
Main NixOS system configuration that:
|
||||
- Imports all modules
|
||||
- Defines system-wide settings
|
||||
- Sets the current theme
|
||||
- Configures hardware and services
|
||||
|
||||
### 3. Module System (`modules/`)
|
||||
Modular architecture with focused components:
|
||||
- **Core**: Base system settings and OmniXY options
|
||||
- **Themes**: Complete color schemes and application theming
|
||||
- **Hardware**: Device-specific configurations
|
||||
- **Desktop**: Window manager and GUI settings
|
||||
- **Development**: Programming tools and environments
|
||||
|
||||
### 4. Home Manager (`home.nix`)
|
||||
User environment management:
|
||||
- User-specific packages
|
||||
- Dotfile configuration
|
||||
- Application settings
|
||||
- Theme integration
|
||||
|
||||
### 5. Package System (`packages/`)
|
||||
Custom Nix packages:
|
||||
- OmniXY utility scripts
|
||||
- Specialized tools
|
||||
- Theme packages
|
||||
|
||||
### 6. Unix Tools (`scripts/`)
|
||||
Focused utilities following Unix philosophy:
|
||||
- System management
|
||||
- Configuration backup
|
||||
- User setup
|
||||
- Build automation
|
||||
|
||||
## Data Flow
|
||||
|
||||
### System Build Process
|
||||
```
|
||||
flake.nix → configuration.nix → modules/*.nix → system build
|
||||
↓ ↓ ↓
|
||||
inputs system opts module config
|
||||
↓ ↓ ↓
|
||||
nixpkgs theme selection packages/services
|
||||
```
|
||||
|
||||
### Theme Application Flow
|
||||
```
|
||||
Theme Selection → Module Configuration → Application Settings
|
||||
↓ ↓ ↓
|
||||
omnixy theme modules/themes/ GTK/Qt/Terminal
|
||||
set <name> <name>.nix theming
|
||||
```
|
||||
|
||||
### User Environment Flow
|
||||
```
|
||||
home.nix → Home Manager → User Packages & Dotfiles
|
||||
↓ ↓ ↓
|
||||
user config evaluation ~/.config/* files
|
||||
```
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Declarative Configuration
|
||||
- All system state defined in Nix expressions
|
||||
- No imperative commands modify system configuration
|
||||
- Changes require rebuild to take effect
|
||||
|
||||
### Immutable System
|
||||
- Built configurations are immutable
|
||||
- Previous generations available for rollback
|
||||
- Atomic upgrades prevent partial failures
|
||||
|
||||
### Module Composition
|
||||
- Features implemented as independent modules
|
||||
- Modules can depend on other modules
|
||||
- Options system provides configuration interface
|
||||
|
||||
### Reproducible Builds
|
||||
- Flake inputs pinned with lock file
|
||||
- Same inputs produce identical outputs
|
||||
- Cross-machine consistency guaranteed
|
||||
|
||||
## Development Architecture
|
||||
|
||||
### Language Support
|
||||
Each language environment includes:
|
||||
- Runtime and tools
|
||||
- Language server protocols (LSPs)
|
||||
- Package managers
|
||||
- Development utilities
|
||||
|
||||
### Shell Environments
|
||||
```
|
||||
Development Shell:
|
||||
nix develop .#<language>
|
||||
↓
|
||||
Language-specific packages
|
||||
↓
|
||||
Configured environment
|
||||
```
|
||||
|
||||
### Tool Integration
|
||||
- Git with lazygit TUI
|
||||
- Terminal with shell integration
|
||||
- Editor with language support
|
||||
- Build systems and debuggers
|
||||
|
||||
## Theme Architecture
|
||||
|
||||
### Unified Theming
|
||||
All applications themed consistently:
|
||||
- Terminal emulators (Alacritty, Kitty)
|
||||
- Text editors (Neovim, VSCode)
|
||||
- Desktop components (Waybar, Hyprland)
|
||||
- GUI applications (GTK, Qt)
|
||||
|
||||
### Color Management
|
||||
```
|
||||
Theme Module → Color Variables → Application Configs
|
||||
↓ ↓ ↓
|
||||
tokyo-night.nix → #7aa2f7 (blue) → terminal.colors.blue
|
||||
```
|
||||
|
||||
### Theme Switching
|
||||
1. Update configuration.nix with new theme
|
||||
2. Rebuild system to apply changes
|
||||
3. All applications automatically use new theme
|
||||
|
||||
## Hardware Support
|
||||
|
||||
### Adaptive Configuration
|
||||
- Automatic hardware detection
|
||||
- GPU-specific optimizations (Intel, AMD, NVIDIA)
|
||||
- Audio system configuration
|
||||
- Network and Bluetooth setup
|
||||
|
||||
### Conditional Modules
|
||||
```nix
|
||||
config = lib.mkIf cfg.hardware.nvidia.enable {
|
||||
# NVIDIA-specific configuration
|
||||
};
|
||||
```
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### System Security
|
||||
- Secure boot support
|
||||
- Firewall configuration
|
||||
- AppArmor profiles
|
||||
- User isolation
|
||||
|
||||
### Authentication
|
||||
- Multi-factor authentication support
|
||||
- Fingerprint integration
|
||||
- FIDO2 security keys
|
||||
- Password management
|
||||
|
||||
## Extensibility
|
||||
|
||||
### Custom Modules
|
||||
- Follow NixOS module structure
|
||||
- Use options for configuration
|
||||
- Implement proper dependencies
|
||||
- Document all options
|
||||
|
||||
### Package Development
|
||||
- Custom packages in `packages/`
|
||||
- Integration with flake outputs
|
||||
- Proper meta information
|
||||
- Cross-platform support
|
||||
|
||||
### Theme Development
|
||||
- Color palette definition
|
||||
- Application configuration
|
||||
- Testing across components
|
||||
- Documentation and examples
|
||||
|
||||
This architecture provides a solid foundation for a reproducible, customizable, and maintainable desktop Linux system.
|
||||
374
docs/COMMANDS.md
Normal file
374
docs/COMMANDS.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# OmniXY Command Reference
|
||||
|
||||
This document provides a comprehensive reference for all OmniXY commands and utilities.
|
||||
|
||||
## Main Command Interface
|
||||
|
||||
### `omnixy`
|
||||
The primary command interface supporting global flags and subcommands.
|
||||
|
||||
**Global Flags**:
|
||||
- `--quiet`, `-q`: Minimal output for scripting
|
||||
- `--json`: Machine-readable JSON output where applicable
|
||||
|
||||
**Subcommands**:
|
||||
- `help`: Show comprehensive help
|
||||
- `info`, `status`: Display system information
|
||||
- `update`, `upgrade`: Update system and flake inputs
|
||||
- `clean`, `gc`: Garbage collection and optimization
|
||||
- `theme`: Theme management
|
||||
- `search`: Package search
|
||||
- `install`: Package installation guide
|
||||
|
||||
## System Management Commands
|
||||
|
||||
### System Information
|
||||
```bash
|
||||
# System overview
|
||||
omnixy info
|
||||
|
||||
# Quiet output (key=value pairs)
|
||||
omnixy --quiet info
|
||||
|
||||
# JSON output for scripting
|
||||
omnixy --json info | jq .system.version
|
||||
```
|
||||
|
||||
### System Updates
|
||||
```bash
|
||||
# Update system with progress indication
|
||||
omnixy update
|
||||
|
||||
# Quiet update for scripts
|
||||
omnixy --quiet update
|
||||
|
||||
# Manual rebuild
|
||||
omnixy-rebuild
|
||||
```
|
||||
|
||||
### System Maintenance
|
||||
```bash
|
||||
# Clean and optimize
|
||||
omnixy clean
|
||||
|
||||
# Show current/new store sizes
|
||||
omnixy clean # Shows before/after sizes
|
||||
|
||||
# Quiet cleanup
|
||||
omnixy --quiet clean
|
||||
```
|
||||
|
||||
## Theme Management Commands
|
||||
|
||||
### Theme Operations
|
||||
```bash
|
||||
# List all available themes
|
||||
omnixy theme list
|
||||
omnixy theme ls
|
||||
|
||||
# Get current theme
|
||||
omnixy theme get
|
||||
omnixy theme current
|
||||
|
||||
# Set new theme
|
||||
omnixy theme set tokyo-night
|
||||
omnixy theme kanagawa
|
||||
```
|
||||
|
||||
### Scriptable Theme Management
|
||||
```bash
|
||||
# List themes (one per line)
|
||||
omnixy --quiet theme list
|
||||
|
||||
# JSON theme information
|
||||
omnixy --json theme list
|
||||
|
||||
# Current theme for scripting
|
||||
current_theme=$(omnixy --quiet theme get)
|
||||
|
||||
# Automated theme cycling
|
||||
themes=($(omnixy --quiet theme list))
|
||||
next_theme=${themes[$(( ($(omnixy --quiet theme list | grep -n "$(omnixy --quiet theme get)" | cut -d: -f1) % ${#themes[@]}) ))]}
|
||||
omnixy theme set "$next_theme"
|
||||
```
|
||||
|
||||
## Package Management Commands
|
||||
|
||||
### Package Search
|
||||
```bash
|
||||
# Search for packages
|
||||
omnixy search firefox
|
||||
omnixy search development-tools
|
||||
|
||||
# Direct nix search
|
||||
nix search nixpkgs firefox
|
||||
```
|
||||
|
||||
### Package Installation
|
||||
```bash
|
||||
# Installation guide (interactive)
|
||||
omnixy install firefox
|
||||
|
||||
# Note: Actual installation requires editing configuration files
|
||||
# and rebuilding the system
|
||||
```
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Development Shells
|
||||
```bash
|
||||
# Language-specific development environments
|
||||
omnixy-dev-shell rust # Rust toolchain
|
||||
omnixy-dev-shell python # Python environment
|
||||
omnixy-dev-shell go # Go development
|
||||
omnixy-dev-shell js # Node.js/JavaScript
|
||||
omnixy-dev-shell node # Alternative for Node.js
|
||||
omnixy-dev-shell c # C/C++ development
|
||||
omnixy-dev-shell cpp # Alternative for C++
|
||||
|
||||
# Using flake development shells
|
||||
nix develop # Default development shell
|
||||
nix develop .#rust # Rust-specific shell
|
||||
nix develop .#python # Python-specific shell
|
||||
nix develop .#node # Node.js-specific shell
|
||||
```
|
||||
|
||||
## Utility Commands
|
||||
|
||||
### Screenshot Management
|
||||
```bash
|
||||
# Interactive region selection (default)
|
||||
omnixy-screenshot
|
||||
omnixy-screenshot region
|
||||
|
||||
# Full screen capture
|
||||
omnixy-screenshot full
|
||||
omnixy-screenshot screen
|
||||
|
||||
# Active window capture
|
||||
omnixy-screenshot window
|
||||
```
|
||||
|
||||
### System Help
|
||||
```bash
|
||||
# Comprehensive help system
|
||||
omnixy help
|
||||
omnixy-help
|
||||
|
||||
# Command-specific help
|
||||
omnixy --help
|
||||
omnixy theme --help
|
||||
```
|
||||
|
||||
## Unix Philosophy Tools
|
||||
|
||||
Located in `scripts/` directory - focused utilities following Unix principles:
|
||||
|
||||
### System Validation
|
||||
```bash
|
||||
# Complete system check
|
||||
./scripts/omnixy-check-system
|
||||
|
||||
# Check only NixOS
|
||||
./scripts/omnixy-check-system --nixos-only
|
||||
|
||||
# Check permissions only
|
||||
./scripts/omnixy-check-system --permissions-only
|
||||
|
||||
# Silent check (exit codes only)
|
||||
./scripts/omnixy-check-system --quiet
|
||||
|
||||
# JSON output
|
||||
OMNIXY_JSON=1 ./scripts/omnixy-check-system
|
||||
```
|
||||
|
||||
### Configuration Management
|
||||
```bash
|
||||
# Create configuration backup
|
||||
backup_path=$(./scripts/omnixy-backup-config)
|
||||
echo "Backup created at: $backup_path"
|
||||
|
||||
# Custom backup location
|
||||
./scripts/omnixy-backup-config /custom/backup/path
|
||||
|
||||
# Install configuration files
|
||||
./scripts/omnixy-install-files
|
||||
|
||||
# Custom source/destination
|
||||
./scripts/omnixy-install-files /source/path /dest/path
|
||||
```
|
||||
|
||||
### User Configuration
|
||||
```bash
|
||||
# Interactive user setup
|
||||
username=$(./scripts/omnixy-configure-user)
|
||||
|
||||
# Non-interactive mode
|
||||
./scripts/omnixy-configure-user alice
|
||||
|
||||
# Custom config files
|
||||
./scripts/omnixy-configure-user alice /etc/nixos/configuration.nix /etc/nixos/home.nix
|
||||
```
|
||||
|
||||
### System Building
|
||||
```bash
|
||||
# Build and switch system
|
||||
./scripts/omnixy-build-system
|
||||
|
||||
# Dry run (test only)
|
||||
./scripts/omnixy-build-system --dry-run
|
||||
|
||||
# Custom configuration
|
||||
./scripts/omnixy-build-system /path/to/config custom-name
|
||||
```
|
||||
|
||||
## Installation Commands
|
||||
|
||||
### Simple Installer
|
||||
```bash
|
||||
# Basic installation
|
||||
./install-simple.sh
|
||||
|
||||
# With options
|
||||
./install-simple.sh --user alice --theme gruvbox --quiet
|
||||
|
||||
# Dry run
|
||||
./install-simple.sh --dry-run
|
||||
|
||||
# Environment variables
|
||||
OMNIXY_USER=bob OMNIXY_THEME=nord ./install-simple.sh --quiet
|
||||
```
|
||||
|
||||
### Interactive Installer
|
||||
```bash
|
||||
# Full interactive experience
|
||||
./install.sh
|
||||
|
||||
# Features styled terminal interface with:
|
||||
# - System verification
|
||||
# - User configuration
|
||||
# - Theme selection
|
||||
# - Feature toggles
|
||||
# - Progress indication
|
||||
```
|
||||
|
||||
### Bootstrap Installation
|
||||
```bash
|
||||
# Remote bootstrap (run on fresh NixOS)
|
||||
curl -fsSL https://raw.githubusercontent.com/thearctesian/omnixy/main/boot.sh | bash
|
||||
|
||||
# Local bootstrap
|
||||
./boot.sh
|
||||
```
|
||||
|
||||
## Advanced Commands
|
||||
|
||||
### Build System Commands
|
||||
```bash
|
||||
# Build without switching
|
||||
nixos-rebuild build --flake .#omnixy
|
||||
|
||||
# Build VM for testing
|
||||
nixos-rebuild build-vm --flake .#omnixy
|
||||
|
||||
# Run VM
|
||||
./result/bin/run-omnixy-vm
|
||||
|
||||
# Check flake evaluation
|
||||
nix flake check
|
||||
|
||||
# Update flake inputs
|
||||
nix flake update
|
||||
```
|
||||
|
||||
### Package Building
|
||||
```bash
|
||||
# Build OmniXY scripts package
|
||||
nix build .#omnixy-scripts
|
||||
|
||||
# Test built scripts
|
||||
./result/bin/omnixy --help
|
||||
|
||||
# Build specific packages
|
||||
nix build .#package-name
|
||||
```
|
||||
|
||||
### Development Commands
|
||||
```bash
|
||||
# Format Nix code
|
||||
nixpkgs-fmt *.nix **/*.nix
|
||||
alejandra *.nix # Alternative formatter
|
||||
|
||||
# Nix code analysis
|
||||
statix check . # Static analysis
|
||||
deadnix . # Dead code detection
|
||||
|
||||
# Show flake info
|
||||
nix flake show
|
||||
nix flake metadata
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Global Settings
|
||||
- `OMNIXY_QUIET=1`: Enable quiet mode for all commands
|
||||
- `OMNIXY_JSON=1`: Enable JSON output where supported
|
||||
- `OMNIXY_USER`: Default username for installation
|
||||
- `OMNIXY_THEME`: Default theme for installation
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Quiet automation
|
||||
export OMNIXY_QUIET=1
|
||||
omnixy update && omnixy clean && echo "Maintenance complete"
|
||||
|
||||
# JSON processing
|
||||
omnixy --json info | jq -r '.system.version'
|
||||
|
||||
# Environment-based installation
|
||||
export OMNIXY_USER=developer
|
||||
export OMNIXY_THEME=tokyo-night
|
||||
./install-simple.sh --quiet
|
||||
```
|
||||
|
||||
## Command Composition Examples
|
||||
|
||||
### System Maintenance Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Complete system maintenance
|
||||
|
||||
echo "Starting system maintenance..."
|
||||
|
||||
# Update system
|
||||
omnixy --quiet update || { echo "Update failed"; exit 1; }
|
||||
|
||||
# Clean system
|
||||
omnixy --quiet clean
|
||||
|
||||
# Verify system health
|
||||
omnixy --quiet info | grep -q "NixOS" || { echo "System check failed"; exit 1; }
|
||||
|
||||
echo "Maintenance complete"
|
||||
```
|
||||
|
||||
### Theme Rotation Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Rotate through available themes
|
||||
|
||||
current=$(omnixy --quiet theme get)
|
||||
themes=($(omnixy --quiet theme list))
|
||||
|
||||
for i in "${!themes[@]}"; do
|
||||
if [[ "${themes[$i]}" == "$current" ]]; then
|
||||
next_index=$(( (i + 1) % ${#themes[@]} ))
|
||||
next_theme="${themes[$next_index]}"
|
||||
omnixy theme set "$next_theme"
|
||||
echo "Switched from $current to $next_theme"
|
||||
break
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
This command reference provides comprehensive coverage of all OmniXY utilities, making it easy to find and use the right tool for any task.
|
||||
441
docs/INSTALLATION.md
Normal file
441
docs/INSTALLATION.md
Normal file
@@ -0,0 +1,441 @@
|
||||
# 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
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# Verify NixOS installation
|
||||
ls /etc/NIXOS
|
||||
nixos-version
|
||||
```
|
||||
|
||||
**Permission Denied Errors**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# Test internet connectivity
|
||||
curl -I https://github.com
|
||||
ping -c 3 cache.nixos.org
|
||||
|
||||
# Check DNS resolution
|
||||
nslookup github.com
|
||||
```
|
||||
|
||||
**Insufficient Space**:
|
||||
```bash
|
||||
# Check available space
|
||||
df -h /
|
||||
du -sh /nix/store
|
||||
|
||||
# Clean up if needed
|
||||
nix-collect-garbage -d
|
||||
```
|
||||
|
||||
### Build Failures
|
||||
|
||||
**Flake Evaluation Errors**:
|
||||
```bash
|
||||
# Check flake syntax
|
||||
nix flake check --show-trace
|
||||
|
||||
# Debug with verbose output
|
||||
nixos-rebuild build --flake .#omnixy --show-trace
|
||||
```
|
||||
|
||||
**Package Build Failures**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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.
|
||||
98
docs/README.md
Normal file
98
docs/README.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# OmniXY Documentation
|
||||
|
||||
## Overview
|
||||
OmniXY is a declarative, reproducible NixOS-based operating system focused on developer productivity and aesthetic customization. Built on top of NixOS, it provides a complete development environment with beautiful themes, modern tools, and a tiling window manager (Hyprland).
|
||||
|
||||
## Table of Contents
|
||||
- [Architecture Overview](./ARCHITECTURE.md)
|
||||
- [Installation Guide](./INSTALLATION.md)
|
||||
- [Configuration System](./CONFIGURATION.md)
|
||||
- [Theme System](./THEMES.md)
|
||||
- [Development Environment](./DEVELOPMENT.md)
|
||||
- [Command Reference](./COMMANDS.md)
|
||||
- [Troubleshooting](./TROUBLESHOOTING.md)
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Install NixOS** - OmniXY requires a base NixOS installation
|
||||
2. **Run Bootstrap** - `curl -fsSL https://raw.githubusercontent.com/thearctesian/omnixy/main/boot.sh | bash`
|
||||
3. **Configure User** - Set your username and select a theme
|
||||
4. **Reboot** - Apply the new configuration
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Declarative Configuration
|
||||
Everything in OmniXY is defined through Nix expressions. Your entire system configuration—packages, services, themes, and settings—is declared in code and version controlled.
|
||||
|
||||
### Reproducibility
|
||||
The same configuration will produce identical systems across different machines. This is achieved through Nix's functional package management and flake lock files.
|
||||
|
||||
### Modularity
|
||||
The system is built from composable modules that can be enabled, disabled, or customized independently. Each module handles a specific aspect of the system.
|
||||
|
||||
### Immutability
|
||||
System packages and configurations are immutable once built. Changes require rebuilding the system, preventing configuration drift and ensuring consistency.
|
||||
|
||||
## System Components
|
||||
|
||||
### Base System (NixOS)
|
||||
- Functional package management
|
||||
- Atomic upgrades and rollbacks
|
||||
- Declarative system configuration
|
||||
- Reproducible builds
|
||||
|
||||
### Window Manager (Hyprland)
|
||||
- Dynamic tiling compositor for Wayland
|
||||
- Smooth animations and effects
|
||||
- Extensive customization options
|
||||
- Modern GPU-accelerated rendering
|
||||
|
||||
### Development Tools
|
||||
- Multiple language environments (Rust, Go, Python, Node.js, etc.)
|
||||
- Git integration with lazygit
|
||||
- Modern terminal emulators (Alacritty, Kitty)
|
||||
- Neovim with LazyVim configuration
|
||||
|
||||
### Theme System
|
||||
- 11 pre-configured color schemes
|
||||
- Unified theming across all applications
|
||||
- Easy theme switching with `omnixy theme set <name>`
|
||||
- Custom theme support
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
omnixy/
|
||||
├── docs/ # This documentation
|
||||
├── configuration.nix # Main system configuration
|
||||
├── flake.nix # Flake definition with inputs/outputs
|
||||
├── home.nix # User environment configuration
|
||||
├── modules/ # System modules
|
||||
│ ├── themes/ # Theme definitions
|
||||
│ ├── hardware/ # Hardware configurations
|
||||
│ └── desktop/ # Desktop environment configs
|
||||
├── packages/ # Custom Nix packages
|
||||
└── scripts/ # Unix philosophy utilities
|
||||
```
|
||||
|
||||
## Philosophy
|
||||
|
||||
OmniXY follows these principles:
|
||||
|
||||
1. **Declarative Over Imperative** - Define what you want, not how to get it
|
||||
2. **Reproducible Builds** - Same input always produces same output
|
||||
3. **Unix Philosophy** - Tools that do one thing well
|
||||
4. **Developer First** - Optimized for programming workflows
|
||||
5. **Beautiful Defaults** - Aesthetic out of the box
|
||||
6. **Extensible** - Easy to customize and extend
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Command Help**: `omnixy help`
|
||||
- **System Info**: `omnixy info`
|
||||
- **GitHub Issues**: https://github.com/TheArctesian/omnixy/issues
|
||||
- **NixOS Manual**: https://nixos.org/manual/nixos/stable/
|
||||
|
||||
## Contributing
|
||||
|
||||
OmniXY is open source and welcomes contributions. See the main README for contribution guidelines.
|
||||
Reference in New Issue
Block a user