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.
- 🌟 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
.
├── 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
- 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
- NixOS or Nix with flakes enabled
- Git
justcommand runner- (Optional) sops for secret management
- Install the
justcommand runner:
nix-env -iA nixpkgs.just- 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
- Generate SOPS key (if using secrets):
just sops-key-
Review and modify the configuration:
- Choose or create a constellation in
constellations/ - Modify
flake.nixto include your system - Adjust hardware configuration as needed
- Choose or create a constellation in
-
Deploy the configuration:
just switch <hostname># 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]# 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 all flake inputs
just update
# Update specific input
just update-input <input-name>commitlint: For commit message lintingdefault: Contains tools to program in this repo
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.nixThe flake.nix provides:
- nixosConfigurations: System configurations for each machine
- packages: Installable packages and ISO images
- devShells: Development environments
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
- Status: Abandonned
- Purpose: Desktop workstation
- Features: GNOME desktop, development tools
- Status: Active
- Purpose: Home server
- Services: Traefik, planned hosting for various services
- Status: Active
- Purpose: Installation ISO
- Features: Basic system for testing and installation
- Status: In Development
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
| 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
This project is open source and available under the Apache v2 license.
- 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