Skip to content

Latest commit

 

History

History
272 lines (197 loc) · 8.32 KB

README.md

File metadata and controls

272 lines (197 loc) · 8.32 KB

airone01/flake

A modular and extensible NixOS configuration system using a custom star-based architecture. This repository contains my personal NixOS configurations for multiple machines and deployments, managed with a comprehensive task runner.

📚 Table of Contents

✨ Features

  • 🌟 Modular "star" system for composable configurations
  • 🛠️ Comprehensive task runner using Just
  • 🔒 Secret management with sops-nix
  • 🚀 Development shells for various tasks
  • 📦 Multiple machine configurations
  • 🔄 Automated formatting and checks
  • 💾 ISO generation capabilities
  • 📁 Direnv support

🏗️ Structure

.
├── asterisms/        # High-level configuration combinations
├── constellations/   # Machine-specific configurations
│   ├── aquarius/    # Server configuration
│   ├── cassiopeia/  # Desktop configuration
│   └── ursamajor/   # ISO configuration
├── lib/             # Helper functions and core modules
├── rockets/         # Development shells
├── secrets/         # Encrypted secrets (using sops-nix)
└── stars/           # Modular configuration units

Key Components

  • Stars: Individual configuration modules that can be composed together
  • Asterisms: Predefined combinations of stars for specific use cases
  • Constellations: Complete system configurations for specific machines
  • Rockets: Development environments for specific tasks
  • Secrets: Encrypted configuration secrets managed with sops-nix

🚀 Getting Started

Prerequisites

  • NixOS or Nix with flakes enabled
  • Git
  • just command runner
  • (Optional) sops for secret management

Installation

  1. Install the just command runner:
nix-env -iA nixpkgs.just
  1. Bootstrap a new system:
just bootstrap <hostname>

This will:

  • Set up the nix channels
  • Install required tools
  • Clone the repository
  • Prepare the system for configuration
  1. Generate SOPS key (if using secrets):
just sops-key

  1. Review and modify the configuration:

    • Choose or create a constellation in constellations/
    • Modify flake.nix to include your system
    • Adjust hardware configuration as needed

  2. Deploy the configuration:

just switch <hostname>

🛠️ Usage

System Management

# Build and switch to configuration
just switch <hostname>

# Test configuration without applying
just test <hostname>

# Build ISO image
just iso [system] [format]

# Clean old generations
just clean [days]

Development Tasks

# Format nix files
just fmt

# Check formatting
just fmt-check

# Run flake checks
just check

# Enter development shell
just develop [shell-name]

# Show changes to nix files
just show-diff

Update Management

# Update all flake inputs
just update

# Update specific input
just update-input <input-name>

Available Development Shells

  • commitlint: For commit message linting
  • default: Contains tools to program in this repo

🏛️ Architecture

The Star System

Stars are the fundamental building blocks of this configuration. Each star is a self-contained NixOS module that can be composed with others.

# Example star structure
stars/
├── gui/             # GUI-related configurations
│   ├── gnome.nix
│   └── hyprland.nix
├── cli/             # CLI tool configurations
│   └── nvim/
└── core/            # Core system configurations
    └── sound.nix

Flake Structure

The flake.nix provides:

  • nixosConfigurations: System configurations for each machine
  • packages: Installable packages and ISO images
  • devShells: Development environments

Secret Management

Secrets are managed using sops-nix with age encryption:

  • Secrets are stored in secrets/
  • Keys are configured in .sops.yaml
  • Each constellation can access only its required secrets
  • Generate keys with just sops-key

📦 Machines

aquarius

  • Status: Abandonned

cassiopeia

  • Purpose: Desktop workstation
  • Features: GNOME desktop, development tools
  • Status: Active

cetus

  • Purpose: Home server
  • Services: Traefik, planned hosting for various services
  • Status: Active

ursamajor

  • Purpose: Installation ISO
  • Features: Basic system for testing and installation
  • Status: In Development

Commit Message Convention

This repository uses conventional commits. Each commit message should be structured as:

<type>(<scope>)[!]: <description>

[body]

[BREAKING CHANGE: ][footer]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore Scopes: See .commitlintrc.yml for valid scopes

📋 Roadmap

Category Task Priority Status
Documentation Add installation guides for each constellation High 🟡 Pending
Testing Add GitHub Actions workflows High 🟢 Complete
Testing Implement basic system tests Medium 🔴 Not Started
Testing Add Nix formatting checks High 🟢 Complete
Security Implement firewall configuration High 🔴 Not Started
Security Add fail2ban configuration Medium 🔴 Not Started
Security Configure automatic security updates High 🔴 Not Started
Security Implement SSH hardening High 🔴 Not Started
Backup Add restic/borgbackup configuration High 🔴 Not Started
Monitoring Set up Prometheus + Grafana Medium 🔴 Not Started
Infrastructure Add Hydra instance Low 🟢 Complete
Infrastructure Add TeamCity instance Low 🔴 Not Started
Infrastructure Add Attic binary cache Medium 🔴 Not Started
Infrastructure Add Mastodon frontend Low 🟢 Complete
Infrastructure Add Lemmy instance Low 🔴 Not Started
Infrastructure Add Invidious instance Low 🔴 Not Started
Infrastructure Add SearXNG instance Medium 🔴 Not Started
Infrastructure Add Gitea instance Medium 🟢 Complete
Infrastructure Add Jellyfin instance Low 🔴 Not Started
Infrastructure Add Vaultwarden instance Low 🔴 Not Started
Infrastructure Add Home Assistant instance Low 🔴 Not Started
Infrastructure Add Paperless-ngx instance Low 🔴 Not Started
Infrastructure Add Syncthing instance Low 🔴 Not Started
Infrastructure Add Calibre-Web instance Low 🔴 Not Started
Infrastructure Add Photoprism instance Low 🔴 Not Started
Architecture Task runner implementation High 🟢 Complete
Architecture Figuring all of this out High 🟣 Always going on

Legend:

  • 🟢 Complete
  • 🟡 In Progress/Partial
  • 🔴 Not Started
  • 🟣 Special

📄 License

This project is open source and available under the Apache v2 license.

🙏 Acknowledgments

  • NixOS for the amazing Linux distribution
  • All the fantastic Nix community members who share their configurations
  • NotAShelf for inspiration
  • casey/just for the fantastic command runner
  • Contributors to all the tools and packages used in this configuration