na-distro

Minimalist Niri-based Wayland desktop configuration with multi-distro support

A modern dotfiles system featuring the Niri scrollable tiling compositor, Fish shell with custom prompt, and comprehensive CLI tooling. Supports both Arch Linux and Ubuntu with automated installation, test suite, and remote SSH deployment.

Features

• Niri Compositor - Scrollable tiling Wayland compositor with elegant window management
• Fish Shell - Modern shell with custom Adwaita-themed prompt and Git integration
• Multi-distro Support - Auto-detects Arch (pacman) or Ubuntu (apt)
• CLI-only Mode - Headless server installations without GUI components
• Remote Bootstrap - One-command SSH deployment to remote servers
• Package Organization - Separate CLI/GUI package lists per distribution
• Comprehensive Testing - Docker-based test suite with 8/8 passing tests
• Hardlinked SSH Config - Bidirectional editing between repo and ~/.ssh/

Quick Start

Fresh Machine Bootstrap

Install on a new machine with a single command — installs git, clones the repo, and runs the full installer:

# Full GUI installation
curl -fsSL https://projects.verestiuc.com/vvlad/na-distro/raw/branch/main/install/install.sh | bash

# CLI-only (servers/headless)
curl -fsSL https://projects.verestiuc.com/vvlad/na-distro/raw/branch/main/install/install.sh | bash -s -- --cli-only

Local Installation

If you already have the repo cloned:

# Full GUI installation (Niri + all tools)
./install/local

# CLI-only installation (servers/headless)
./install/local --cli-only

# Skip root customizations
./install/local --no-root

# Combined flags
./install/local --cli-only --no-root

Remote Installation

Deploy to a remote server via SSH:

# Basic remote installation (always CLI-only)
./install/remote user@server.example.com

# Custom SSH port
./install/remote -p 2222 user@server.local

# With SSH key
./install/remote -i ~/.ssh/id_rsa user@192.168.1.100

# Dry run (preview without executing)
./install/remote --dry-run user@server

What's Included

Full Installation (GUI)

Window Manager & Desktop:

• Niri - Scrollable tiling Wayland compositor
• Waybar - Status bar with custom styling
• Mako - Notification daemon
• SwayOSD - On-screen display for volume/brightness
• Swaylock + Swayidle - Screen locking and idle management
• UWSM - Universal Wayland Session Manager

Applications:

• Alacritty - Terminal emulator
• Neovim - Modern Vim with Lua configuration and Adwaita Pastel Dark theme
• Walker - Application launcher
• Various GUI tools (evince, loupe, etc.)

Theming:

• Adwaita Pastel Dark theme
• Custom Niri layouts with center-focused toggle
• Qt/GTK theming integration
• Papirus icon theme

CLI-only Installation (Servers)

Shell:

• Fish shell with custom prompt
• Syntax highlighting and completions
• Git-aware prompt with branch info

CLI Tools:

• bat - Better cat with syntax highlighting
• fzf - Fuzzy finder
• htop/btop - System monitors
• jq - JSON processor
• mise - Runtime version manager
• git - Version control

System:

• Docker + docker-compose
• SSH configuration with hardlinks
• Gnome Keyring + gcr-ssh-agent
• Systemd user services

Installation Details

Directory Structure

~/.config/              # Configuration symlinks
~/.local/share/         # Application data
~/.ssh/                 # SSH config (hardlinked)
~/.local/state/config-backups/  # Backup of replaced configs

Package Organization

config/packages/
├── arch/
│   ├── cli/packages.txt    # Arch CLI tools (bat, fish, git, etc.)
│   └── gui/packages.txt    # Arch GUI tools (niri, waybar, etc.)
└── ubuntu/
    ├── cli/packages.txt    # Ubuntu CLI tools
    └── gui/packages.txt    # Ubuntu GUI tools

Flags

• --cli-only - Install only CLI tools, skip all GUI configurations
• --no-root - Skip root user customizations (fish, greetd, etc.)
• --fingerprint - Enable fingerprint authentication for swaylock
• --gaming - Install gaming support (Wine tray icon proxy)

Installer flags are saved to ~/.config/na-distro/install.flags and reused on subsequent runs.

Remote Bootstrap

The install/remote script enables one-command deployment to remote servers:

Features:

• Always uses --cli-only mode (perfect for servers)
• Git-based: clones repository to ~/.local/share/na-distro
• Idempotent: safe to run multiple times
• Interactive confirmation with dry-run mode
• SSH agent forwarding for private repos

Usage:

# Deploy to server
./install/remote user@server.example.com

# Custom repository
./install/remote -r https://example.com/your/dotfiles.git user@server

# Custom installation directory
./install/remote -d /opt/config user@server

Testing

Comprehensive Docker-based test suite with isolation:

# Run all tests (Arch + Ubuntu)
./test/run_tests.fish

# Test specific distro
./test/run_tests.fish --distro arch
./test/run_tests.fish --distro ubuntu

# Run specific test
./test/run_tests.fish --test test_cli_only_flag.fish

# Interactive debugging
./test/run_tests.fish --interactive --distro arch

Test Coverage:

• Basic installation
• CLI-only mode
• No-root flag
• SSH hardlinks
• All tests pass on both Arch and Ubuntu (8/8 suites)

Supported Distributions

Arch Linux / CachyOS

• Full support with pacman
• AUR packages via paru/yay
• All GUI components available

Ubuntu / Debian

• Full support with apt
• Mise installed as binary (not in repos)
• Most GUI components available (some need manual install)

Package Manager Detection

The installer automatically detects your distribution and uses the appropriate package manager. No configuration needed.

Configuration Files

Niri:

• config/niri/config.kdl - Main configuration
• config/niri/theme.kdl - Colors, gaps, borders, shadows
• config/niri/layout-state.kdl - Toggleable layout settings
• config/niri/host.kdl - Host-specific config (not in repo)

Fish:

• config/fish/conf.d/ - Configuration snippets
• config/fish/functions/ - Custom functions
• config/fish/completions/ - Command completions

SSH:

• config/ssh/config - Hardlinked to ~/.ssh/config
• config/ssh/.gitignore - Hardlinked to ~/.ssh/.gitignore
• ~/.ssh/config.local - Machine-specific overrides (not in repo)

Customization

Host-specific Niri Config

Create ~/.config/niri/host.kdl for host-specific settings:

// Example: host-specific monitor configuration
output "HDMI-A-1" {
    mode "1920x1080@60"
}

SSH Local Overrides

Use ~/.ssh/config.local for machine-specific SSH config:

Host work-server
    HostName 192.168.1.100
    User admin
    IdentityFile ~/.ssh/work_key

Custom Package Lists

Edit package files in config/packages/{arch,ubuntu}/{cli,gui}/packages.txt to customize installed packages.

System Requirements

Minimum (CLI-only):

• Linux (Arch or Ubuntu/Debian)
• Git
• Bash or sh
• 100MB disk space

Full GUI:

• Wayland-compatible graphics drivers
• 1GB disk space for all packages
• Niri compositor support

Troubleshooting

Remote Bootstrap Fails

# Check SSH connectivity first
ssh user@server

# Verify git is installed on remote
ssh user@server "which git"

# Use dry-run to preview
./install/remote --dry-run user@server

Package Installation Issues

The installer handles missing packages gracefully. On Ubuntu, some GUI packages may need manual installation:

# Check what failed
grep "warning:" ~/.local/state/config-backups/*/install.log

Test Failures

# Rebuild Docker images
./test/run_tests.fish --distro arch

# Check specific test
./test/run_tests.fish --test test_basic_install.fish --verbose

Development

Adding New Packages

1. Edit appropriate package file: config/packages/{distro}/{cli,gui}/packages.txt
2. Test installation: ./install/local --cli-only (or without for GUI)
3. Add to version control: git add config/packages/ && git commit

Running Tests

Tests use Docker for isolation and reproducibility:

# All tests
./test/run_tests.fish

# Specific test on specific distro
./test/run_tests.fish --test test_ssh_hardlinks.fish --distro ubuntu

# No rebuild (faster iteration)
./test/run_tests.fish --no-build

Creating New Tests

1. Create test/test_yourfeature.fish
2. Use helper functions from test/helpers.fish
3. Run and verify: ./test/run_tests.fish --test test_yourfeature.fish

Repository Structure

.
├── bin/                    # Utility scripts and documentation
├── config/                 # All configuration files
│   ├── fish/              # Fish shell config
│   ├── niri/              # Niri compositor config
│   ├── waybar/            # Status bar config
│   ├── ssh/               # SSH config (hardlinked)
│   ├── packages/          # Package lists by distro/group
│   └── ...                # Other tool configs
├── install/               # Installation scripts
│   ├── install.sh         # Bootstrap: installs git, clones repo, runs local
│   ├── local              # Local installation script
│   ├── remote             # Remote SSH bootstrap script
│   └── stages/            # Installation stage scripts
└── test/                  # Docker-based test suite
    ├── Dockerfile.arch    # Arch Linux test image
    ├── Dockerfile.ubuntu  # Ubuntu test image
    ├── helpers.fish       # Test framework
    └── test_*.fish        # Test files

Credits

• Niri - https://github.com/YaLTeR/niri
• Fish Shell - https://fishshell.com
• Adwaita Theme - GNOME Project
• Based on scrollable tiling window management philosophy

License

Personal dotfiles configuration. Use at your own discretion.

Contributing

This is a personal configuration repository. Feel free to fork and adapt to your needs.

Links

• Repository: https://projects.verestiuc.com/vvlad/na-distro
• Issues: Report via git repository
• Documentation: See bin/README.md and test/README.md