This commit is contained in:
mjallen18
2026-02-10 19:44:35 -06:00
parent 09d9b010b7
commit 535fdc2f86
18 changed files with 2646 additions and 389 deletions

View File

@@ -113,6 +113,17 @@ sudo nixos-rebuild switch --flake .#hostname
home-manager switch --flake .#username@hostname
```
## Documentation
Comprehensive documentation is available in the [docs](./docs) directory:
- [Getting Started](./docs/getting-started.md) - Instructions for setting up new systems
- [Architecture](./docs/architecture.md) - Overview of the repository structure
- [System Configurations](./docs/systems/README.md) - Details about each system
- [Home Assistant](./docs/home-assistant/README.md) - Home Assistant setup and automations
- [Custom Modules](./docs/modules/README.md) - Details about reusable configuration modules
- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
## License
This project is licensed under the MIT License - see the LICENSE file for details.

12
docs/README.md Normal file
View File

@@ -0,0 +1,12 @@
# Documentation
This directory contains comprehensive documentation for the NixOS configuration.
## Contents
- [Getting Started](./getting-started.md) - Instructions for setting up new systems
- [System Configurations](./systems/README.md) - Detailed information about each system
- [Home Assistant](./home-assistant/README.md) - Documentation for the Home Assistant setup
- [Custom Modules](./modules/README.md) - Information about reusable modules
- [Architecture](./architecture.md) - Overview of the repository architecture
- [Troubleshooting](./troubleshooting.md) - Common issues and solutions

105
docs/architecture.md Normal file
View File

@@ -0,0 +1,105 @@
# Repository Architecture
This document provides an overview of the repository architecture, explaining how the various components fit together.
## Overview
This NixOS configuration repository is built using [Nix Flakes](https://nixos.wiki/wiki/Flakes) and [Snowfall Lib](https://github.com/snowfallorg/lib) to provide a modular, maintainable configuration for multiple systems.
## Directory Structure
```
.
├── checks/ # Pre-commit hooks and other checks
├── flake.nix # Main flake configuration
├── homes/ # Home-manager configurations for users
│ ├── aarch64-darwin/ # macOS home configurations
│ ├── aarch64-linux/ # ARM Linux home configurations
│ └── x86_64-linux/ # x86 Linux home configurations
├── modules/ # Reusable configuration modules
│ ├── home/ # Home-manager modules
│ └── nixos/ # NixOS system modules
│ ├── boot/ # Boot configuration modules
│ ├── desktop/ # Desktop environment modules
│ ├── hardware/ # Hardware-specific modules
│ ├── homeassistant/ # Home Assistant modules
│ ├── network/ # Network configuration modules
│ ├── services/ # Service configuration modules
│ └── ... # Other module categories
├── overlays/ # Nixpkgs overlays
├── packages/ # Custom package definitions
├── secrets/ # Encrypted secrets (managed with sops-nix)
└── systems/ # System-specific configurations
├── aarch64-darwin/ # macOS system configurations
├── aarch64-linux/ # ARM Linux system configurations
└── x86_64-linux/ # x86 Linux system configurations
├── jallen-nas/ # NAS server configuration
├── matt-nixos/ # Desktop configuration
├── nuc-nixos/ # NUC configuration
├── pi4/ # Raspberry Pi 4 configuration
└── ... # Other system configurations
```
## Flake Structure
The `flake.nix` file defines the inputs (external dependencies) and outputs (configurations) of this repository:
### Inputs
- **nixpkgs-unstable**: The unstable channel of Nixpkgs
- **nixpkgs-stable**: The stable channel of Nixpkgs (25.11)
- **home-manager**: User environment management
- **snowfall-lib**: Library for structuring flake repositories
- **impermanence**: Persistent state management
- **lanzaboote**: Secure boot implementation
- **nixos-hardware**: Hardware-specific configurations
- **sops-nix**: Secret management
- **disko**: Disk partitioning and formatting
- **And more specialized inputs**
### Outputs
The outputs are generated using Snowfall Lib's `mkFlake` function, which automatically discovers and assembles:
- **NixOS system configurations**: For each system in the `systems/` directory
- **Home Manager configurations**: For each configuration in the `homes/` directory
- **Packages**: From the `packages/` directory
- **Modules**: From the `modules/` directory
- **Overlays**: From the `overlays/` directory
## Module System
The module system uses a modular approach where:
1. **Common modules** are defined in `modules/nixos/` and `modules/home/`
2. **System-specific modules** are defined in `systems/<architecture>/<hostname>/`
Each module follows the NixOS module pattern, with:
- `default.nix`: Main module implementation
- `options.nix`: Option declarations
## Integration with Snowfall Lib
Snowfall Lib provides:
1. **Automatic discovery** of modules, overlays, and packages
2. **Consistent structure** across the repository
3. **Common utilities** for working with flakes
## Secrets Management
Secrets are managed using [sops-nix](https://github.com/Mic92/sops-nix), with:
- Encrypted secret files in the `secrets/` directory
- `.sops.yaml` configuration file in the root
- Key management integrated into the configuration
## Deployment Process
Systems are built and deployed using:
```bash
nixos-rebuild switch --flake .#hostname
```
This command:
1. Evaluates the flake for the specified hostname
2. Builds the resulting configuration
3. Activates it on the current system

172
docs/getting-started.md Normal file
View File

@@ -0,0 +1,172 @@
# Getting Started
This guide will help you get started with this NixOS configuration repository.
## Prerequisites
- Basic knowledge of NixOS and the Nix language
- Git installed on your system
- Physical access to the machine you want to configure
## Initial Setup
### 1. Cloning the Repository
Clone this repository to your local machine:
```bash
git clone ssh://nix-apps@localhost:2222/mjallen/nix-config.git
cd nix-config
```
### 2. Setting Up a New System
#### Option 1: Using an Existing Configuration
If you're setting up a new machine that should be identical to an existing configuration:
1. Boot from a NixOS installation media
2. Mount your target partitions to `/mnt`
3. Clone this repository:
```bash
nixos-enter
cd /mnt
mkdir -p /mnt/etc/nixos
git clone ssh://nix-apps@localhost:2222/mjallen/nix-config.git /mnt/etc/nixos
```
4. Install NixOS with the desired system profile:
```bash
nixos-install --flake /mnt/etc/nixos#hostname
```
Replace `hostname` with the target system name (e.g., `matt-nixos`, `jallen-nas`, etc.)
#### Option 2: Creating a New System Configuration
If you're adding a completely new system:
1. Create a new directory for your system configuration:
```bash
mkdir -p systems/$(uname -m)-linux/new-hostname
```
2. Create the basic configuration files:
```bash
cat > systems/$(uname -m)-linux/new-hostname/default.nix << EOF
{ lib, pkgs, ... }:
{
imports = [
./hardware-configuration.nix
# Add other needed module imports here
];
networking.hostName = "new-hostname";
# Add your system-specific configuration here
}
EOF
```
3. Generate the hardware configuration:
```bash
nixos-generate-config --no-filesystems --dir systems/$(uname -m)-linux/new-hostname/
```
4. Add your new system to the flake by adding it to the `hosts` section in `flake.nix`
5. Build and install the configuration:
```bash
sudo nixos-rebuild switch --flake .#new-hostname
```
## Secret Management
### Setting Up Sops-Nix
1. Create a GPG key if you don't already have one:
```bash
gpg --full-generate-key
```
2. Add your key to `.sops.yaml`:
```bash
# Get your key fingerprint
gpg --list-secret-keys --keyid-format=long
# Edit the .sops.yaml file to add your key
```
3. Create a new encrypted secret:
```bash
sops secrets/newsecret.yaml
```
## Common Tasks
### Updating the Repository
```bash
git pull
sudo nixos-rebuild switch --flake .#hostname
```
### Adding a New Package
1. For standard packages, add them to your system or home configuration:
```nix
environment.systemPackages = with pkgs; [
new-package
];
```
2. For custom packages, add them to the `packages` directory:
```bash
mkdir -p packages/new-package
# Create the necessary Nix files
```
### Adding a New Module
1. Create a new module directory:
```bash
mkdir -p modules/nixos/new-module
```
2. Create the module files:
```bash
# Create options.nix
cat > modules/nixos/new-module/options.nix << EOF
{ lib, namespace, ... }:
with lib;
{
options.${namespace}.new-module = {
enable = mkEnableOption "Enable new module";
# Add other options here
};
}
EOF
# Create default.nix
cat > modules/nixos/new-module/default.nix << EOF
{ config, lib, namespace, ... }:
let
cfg = config.${namespace}.new-module;
in
{
imports = [ ./options.nix ];
config = lib.mkIf cfg.enable {
# Add your configuration here
};
}
EOF
```
3. Import your module in your system configuration:
```nix
imports = [
# ...
../../../modules/nixos/new-module
];
${namespace}.new-module.enable = true;
```

View File

@@ -0,0 +1,188 @@
# Home Assistant Configuration
This document provides comprehensive information about the Home Assistant setup in this NixOS configuration.
## Overview
Home Assistant is configured as a NixOS service with custom components, integrations, and automations. The configuration uses a modular approach with separate files for different aspects of the setup.
## Module Structure
The Home Assistant configuration is organized in the following structure:
```
modules/nixos/homeassistant/
├── automations/ # Automation configurations
│ ├── lightswitch/ # Light switch automations
│ └── motion-light/ # Motion-activated light automations
├── default.nix # Main module configuration
├── options.nix # Module options definition
└── services/ # Related service configurations
├── govee2mqtt/ # Govee integration via MQTT
├── homeassistant/ # Core Home Assistant service
├── music-assistant/ # Music Assistant integration
├── thread/ # Thread border router
└── zigbee2mqtt/ # Zigbee to MQTT bridge
```
## Installation
The Home Assistant module is enabled in the system configuration by setting:
```nix
mjallen.services.home-assistant.enable = true;
```
This activates Home Assistant and related services such as MQTT, Zigbee2MQTT, and the Matter server.
## Configuration Options
The module provides several configuration options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enable` | boolean | `false` | Enable Home Assistant and related services |
| `mosquittoPort` | integer | `1883` | Port for the MQTT broker |
| `zigbee2mqttPort` | integer | `8080` | Port for the Zigbee2MQTT web interface |
| `zigbeeDevicePath` | string | `/dev/ttyUSB0` | Path to the Zigbee USB device |
## Core Services
### Home Assistant
The main Home Assistant service is configured in `services/homeassistant/default.nix` with:
- PostgreSQL database backend
- Custom components
- Custom Lovelace modules
- HTTPS access with authentication
- Integration with other services
### MQTT
MQTT is used as a messaging protocol for various smart home devices. The Mosquitto MQTT broker is automatically configured when Home Assistant is enabled.
### Zigbee2MQTT
Zigbee2MQTT allows integration with Zigbee devices. It's configured with:
- Automatic discovery for Home Assistant
- OTA updates for Zigbee devices
- Web interface for management
### Thread Border Router
The Thread Border Router provides integration with Thread-based devices like Matter devices.
## Custom Components
The following custom components are included:
- `ha-anycubic` - Anycubic 3D printer integration
- `ha-bambulab` - Bambu Lab 3D printer integration
- `ha-bedjet` - BedJet climate control integration
- `ha-gehome` - GE Home appliance integration
- `ha-icloud3` - Enhanced iCloud device tracking
- `ha-local-llm` - Local LLM integration
- `ha-mail-and-packages` - Mail and package delivery tracking
- `ha-nanokvm` - NanoKVM integration
- `ha-openhasp` - openHASP integration for DIY displays
- `ha-overseerr` - Overseerr media request integration
- `ha-petlibro` - PetLibro pet feeder integration
- `ha-wyzeapi` - Wyze device integration
## Automations
### Light Switch Automations
The light switch automations handle physical switch inputs for controlling smart lights.
### Motion Light Automations
Motion light automations turn lights on when motion is detected and off after a period of inactivity.
### Custom Automations
Additional automations are placed in the `/etc/hass` directory and are included in the Home Assistant configuration. These include:
- `fountain_automation.yaml` - Toggles the water dispensing mode on the Dockstream Smart RFID Fountain every 15 minutes between constant and intermittent flow.
## Smart Home Devices
The configuration includes support for various smart home devices:
### Lighting
- Various smart lights throughout the home
### Climate
- Smart thermostat
- Humidifier control
### Pet Care
- Dockstream Smart RFID Fountain with scheduling
- Smart pet feeders for pets named Joey and Luci
- Litter-Robot 4 smart litter box
### Media
- Google Cast devices
- Smart TVs
- Media players
### Sensors
- Temperature, humidity, and motion sensors
- Door and window sensors
- Presence detection
## Integration with Other Services
Home Assistant is integrated with:
- **Music Assistant** - For enhanced music streaming capabilities
- **Govee Integration** - For Govee smart devices
- **Matter** - For Matter-compatible devices
## Adding New Automations
To add a new automation:
1. Create a YAML file with the automation definition
2. Place it in `/etc/hass`
3. The automation will be automatically included in Home Assistant
Example automation format:
```yaml
alias: "Automation Name"
description: "Description of what the automation does"
trigger:
- platform: state
entity_id: binary_sensor.motion_sensor
to: "on"
condition: []
action:
- service: light.turn_on
target:
entity_id: light.living_room
mode: single
```
## Troubleshooting
### Common Issues
1. **Zigbee Device Pairing Issues**
- Make sure the Zigbee coordinator is properly connected
- Check the Zigbee2MQTT logs for errors
2. **Service Unavailable**
- Check if all related services are running
- Verify firewall rules allow access to the services
3. **Database Issues**
- Check PostgreSQL service status
- Verify database connection settings

View File

@@ -0,0 +1,148 @@
# Home Assistant Automations
This document details the automations configured in the Home Assistant setup.
## Automation Types
Automations in this configuration are managed in several ways:
1. **Module-Based Automations**: Defined in Nix modules within the `modules/nixos/homeassistant/automations/` directory
2. **YAML Automations**: Defined in YAML files and included via the `automation manual` directive
3. **UI-Created Automations**: Created through the Home Assistant UI and stored in `automations.yaml`
## Module-Based Automations
### Light Switch Automations
**Location**: `modules/nixos/homeassistant/automations/lightswitch/`
These automations link physical light switches to smart lights:
- **Bedroom Light Switch**: Controls the bedroom lights
- **Living Room Light Switch**: Controls the living room lights
- **Bedroom Closet Lights**: Controls the closet lights
### Motion-Activated Light Automations
**Location**: `modules/nixos/homeassistant/automations/motion-light/`
These automations turn lights on when motion is detected and off after a period of inactivity.
## YAML Automations
### Fountain Cycling Automation
**Location**: `/etc/nixos/fountain_automation.yaml`
This automation toggles the water dispensing mode on the Dockstream Smart RFID Fountain every 15 minutes:
```yaml
alias: "Fountain Cycle Mode"
description: "Toggles fountain water mode every 15 minutes between constant and intermittent flow"
trigger:
- platform: time_pattern
minutes: "/15" # Every 15 minutes
condition: []
action:
- service: select.select_next
target:
entity_id: select.dockstream_smart_rfid_fountain_water_dispensing_mode
mode: single
id: fountain_cycle_mode
```
This automation:
1. Triggers every 15 minutes
2. Uses the `select.select_next` service to toggle between the two available options:
- "Flowing Water (Constant)"
- "Intermittent Water (Scheduled)"
The fountain is also configured with:
- Water Interval: 10 minutes
- Water Dispensing Duration: 15 minutes
## Creating New Automations
### Method 1: Module-Based Automation
For reusable, complex automations that should be managed in code:
1. Create a new directory in `modules/nixos/homeassistant/automations/`
2. Create a `default.nix` file with the automation logic
Example:
```nix
{ config, lib, ... }:
{
config = {
services.home-assistant.config."automation manual" = [
{
alias = "Example Automation";
description = "Example automation created via Nix module";
trigger = [
{
platform = "state";
entity_id = "binary_sensor.example_sensor";
to = "on";
}
];
action = [
{
service = "light.turn_on";
target.entity_id = "light.example_light";
}
];
mode = "single";
}
];
};
}
```
### Method 2: YAML Automation
For simpler automations:
1. Create a YAML file with the automation definition
2. Place it in `/etc/hass/`
Example:
```yaml
alias: "Example Automation"
description: "Example automation in YAML"
trigger:
- platform: state
entity_id: binary_sensor.example_sensor
to: "on"
action:
- service: light.turn_on
target:
entity_id: light.example_light
mode: single
```
### Method 3: UI Creation
For quick prototyping or simple automations:
1. Go to Home Assistant UI > Settings > Automations & Scenes
2. Click "+ Add Automation"
3. Configure using the UI editor
## Testing Automations
To test an automation:
1. In the Home Assistant UI, go to Developer Tools > Services
2. Select `automation.trigger` as the service
3. Enter the entity_id of your automation in the service data field
4. Click "Call Service" to trigger the automation manually
## Troubleshooting
If an automation isn't working as expected:
1. Check the Home Assistant logs for errors
2. Verify entity names and service calls are correct
3. Test individual triggers and actions separately
4. Use the "Debug" section in the automation editor to trace execution

View File

@@ -0,0 +1,96 @@
# Pet Fountain Automation
This document details the automation for the Dockstream Smart RFID Fountain device.
## Overview
The Dockstream Smart RFID Fountain is a smart pet fountain controlled through Home Assistant. A custom automation has been created to toggle the water dispensing mode between constant flow and intermittent flow every 15 minutes. This cycling helps keep the water fresh while reducing energy consumption.
## Fountain Configuration
The Dockstream Smart RFID Fountain has the following settings in Home Assistant:
| Setting | Entity ID | Value | Description |
|---------|-----------|-------|-------------|
| Water Dispensing Mode | `select.dockstream_smart_rfid_fountain_water_dispensing_mode` | Toggles between modes | Controls how water flows |
| Water Interval | `number.dockstream_smart_rfid_fountain_water_interval` | 10 minutes | Time between water dispensing in intermittent mode |
| Water Dispensing Duration | `number.dockstream_smart_rfid_fountain_water_dispensing_duration` | 15 minutes | How long water flows in intermittent mode |
| Cleaning Cycle | `number.dockstream_smart_rfid_fountain_cleaning_cycle` | 14 days | Reminder interval for cleaning |
## Available Modes
The fountain supports two water dispensing modes:
1. **Flowing Water (Constant)** - Water flows continuously
2. **Intermittent Water (Scheduled)** - Water flows according to the interval and duration settings
## Automation Details
The fountain cycling automation is defined in `/etc/nixos/fountain_automation.yaml`:
```yaml
alias: "Fountain Cycle Mode"
description: "Toggles fountain water mode every 15 minutes between constant and intermittent flow"
trigger:
- platform: time_pattern
minutes: "/15" # Every 15 minutes
condition: []
action:
- service: select.select_next
target:
entity_id: select.dockstream_smart_rfid_fountain_water_dispensing_mode
mode: single
id: fountain_cycle_mode
```
### How It Works
1. **Trigger**: The automation runs every 15 minutes based on the time pattern trigger
2. **Action**: It uses the `select.select_next` service to toggle to the next available option
3. **Mode**: Set to "single" to prevent multiple executions if triggers overlap
## Installation
The automation is included in Home Assistant via the `automation manual` directive in the Home Assistant configuration:
```yaml
"automation manual" = "!include_dir_merge_list /etc/hass";
```
The YAML file needs to be placed in the `/etc/hass` directory to be loaded.
## Testing
To manually test the automation:
1. In Home Assistant UI, go to Developer Tools > Services
2. Select `automation.trigger` as the service
3. Enter the following service data:
```yaml
entity_id: automation.fountain_cycle_mode
```
4. Click "Call Service" to trigger the automation
## Customizing
To adjust the cycling interval:
1. Edit the YAML file at `/etc/nixos/fountain_automation.yaml`
2. Change the `minutes` value in the trigger section (e.g., from `"/15"` to `"/30"` for every 30 minutes)
3. Save the file
4. Restart Home Assistant or reload automations
To adjust fountain settings:
1. In Home Assistant UI, go to Settings > Devices & Services
2. Find the Dockstream Smart RFID Fountain device
3. Adjust the water interval or dispensing duration settings
## Troubleshooting
If the automation is not working as expected:
1. Check that the entity ID is correct and the fountain is online
2. Verify that Home Assistant is including the automation file correctly
3. Look for errors in the Home Assistant logs related to the automation or the fountain
4. Try manually controlling the fountain to ensure it responds to commands

116
docs/modules/README.md Normal file
View File

@@ -0,0 +1,116 @@
# Custom Modules
This directory contains documentation for the custom modules used in this NixOS configuration.
## Module Types
The repository uses two main types of modules:
1. **NixOS Modules** - System-level configurations in `modules/nixos/`
2. **Home Manager Modules** - User-level configurations in `modules/home/`
## NixOS Modules
These modules configure the system-level aspects of NixOS:
- [Boot Modules](./boot.md) - Boot loader and kernel configurations
- [Desktop Modules](./desktop.md) - Desktop environment configurations
- [Development Modules](./development.md) - Development tools and environments
- [Hardware Modules](./hardware.md) - Hardware-specific configurations
- [Home Assistant Modules](./homeassistant.md) - Home automation configuration
- [Networking Modules](./network.md) - Network configuration and services
- [Security Modules](./security.md) - Security-related configurations
- [Services Modules](./services.md) - Various service configurations
- [System Modules](./system.md) - General system configurations
- [Virtualization Modules](./virtualization.md) - Virtualization and containerization
## Home Manager Modules
These modules configure user environments:
- [Applications](./home/applications.md) - User applications
- [Desktop](./home/desktop.md) - User desktop environments
- [Development](./home/development.md) - User development environments
- [Media](./home/media.md) - Media applications
- [Shell](./home/shell.md) - Shell configurations
## Module Structure
Each module follows a standard structure:
```
modules/nixos/example-module/
├── default.nix # Main implementation
├── options.nix # Option declarations
└── submodule/ # Optional submodules
└── default.nix # Submodule implementation
```
### default.nix
The `default.nix` file contains the main implementation of the module:
```nix
{
config,
lib,
pkgs,
namespace,
...
}:
let
cfg = config.${namespace}.example-module;
in
{
imports = [ ./options.nix ];
config = lib.mkIf cfg.enable {
# Module implementation when enabled
};
}
```
### options.nix
The `options.nix` file declares the module's configuration options:
```nix
{ lib, namespace, ... }:
with lib;
let
inherit (lib.${namespace}) mkOpt;
in
{
options.${namespace}.example-module = {
enable = mkEnableOption "enable example module";
# Other option declarations
};
}
```
## Using Modules
To use a module in your system configuration:
1. Enable the module in your system configuration:
```nix
{ config, ... }:
{
mjallen.example-module = {
enable = true;
# Other options
};
}
```
## Creating New Modules
To create a new module:
1. Create a new directory in `modules/nixos/` or `modules/home/`
2. Create `default.nix` and `options.nix` files
3. Implement your module functionality
4. Import the module in your system configuration
See the [Getting Started](../getting-started.md) guide for more details on creating modules.

View File

@@ -0,0 +1,190 @@
# Home Assistant Module
This document details the Home Assistant module configuration.
## Module Structure
The Home Assistant module is organized in the following structure:
```
modules/nixos/homeassistant/
├── automations/ # Automation configurations
│ ├── lightswitch/ # Light switch automations
│ └── motion-light/ # Motion-activated light automations
├── default.nix # Main module configuration
├── options.nix # Module options definition
└── services/ # Related service configurations
├── govee2mqtt/ # Govee integration via MQTT
├── homeassistant/ # Core Home Assistant service
├── music-assistant/ # Music Assistant integration
├── thread/ # Thread border router
└── zigbee2mqtt/ # Zigbee to MQTT bridge
```
## Module Options
The module is configured through options defined in `options.nix`:
```nix
options.${namespace}.services.home-assistant = {
enable = mkEnableOption "enable home-assistant";
mosquittoPort = mkOpt types.int 1883 "Port for MQTT";
zigbee2mqttPort = mkOpt types.int 8080 "Port for zigbee2mqtt web interface";
zigbeeDevicePath = mkOpt types.str "/dev/ttyUSB0" "Path to zigbee usb device";
};
```
## Main Configuration
The main module configuration in `default.nix` includes:
1. **Activation Scripts** - For setting up custom components
2. **Service Configurations** - For Matter, PostgreSQL, etc.
3. **Firewall Rules** - For allowing required ports
```nix
config = lib.mkIf cfg.enable {
# Activation script for custom components
system.activationScripts.installCustomComponents = ''
chown -R hass:hass ${config.services.home-assistant.configDir}
chmod -R 750 ${config.services.home-assistant.configDir}
'';
# Service configurations
services = {
matter-server.enable = true;
postgresql = {
enable = false;
ensureDatabases = [ "hass" ];
ensureUsers = [
{
name = "hass";
ensureDBOwnership = true;
}
];
};
};
# Firewall rules
networking.firewall.allowedTCPPorts = [
cfg.mosquittoPort
cfg.zigbee2mqttPort
8095 # music-assistant
8097 # home-assistant
5580 # matter-server
];
};
```
## Home Assistant Service
The core Home Assistant service configuration in `services/homeassistant/default.nix` includes:
1. **Package Selection** - Using the standard Home Assistant package
2. **Component Configuration** - Enabling required components
3. **Custom Components** - Adding custom components from packages
4. **Lovelace Modules** - Adding custom UI components
5. **Integration Configuration** - Setting up integrations with other systems
```nix
services.home-assistant = {
enable = true;
package = pkgs.home-assistant;
openFirewall = true;
configDir = "/var/lib/homeassistant";
configWritable = true;
# Components
extraComponents = [
"mqtt"
"zha"
"homekit"
# ... many more components
];
# Custom components
customComponents = [
# ... custom components
];
# Lovelace modules
customLovelaceModules = [
# ... custom UI modules
];
# Configuration
config = {
# ... Home Assistant configuration
};
};
```
## Related Services
### Zigbee2MQTT
The Zigbee2MQTT service in `services/zigbee2mqtt/default.nix` connects Zigbee devices to MQTT:
```nix
services.zigbee2mqtt = {
enable = true;
settings = {
mqtt = {
server = "mqtt://localhost:${toString cfg.mosquittoPort}";
};
serial = {
port = cfg.zigbeeDevicePath;
};
# ... additional settings
};
};
```
### MQTT
MQTT is configured as a dependency for the Home Assistant module.
### Thread Border Router
The Thread Border Router in `services/thread/default.nix` provides Thread network connectivity for Matter devices.
## Automations
The module includes predefined automations in the `automations/` directory:
1. **Light Switch Automations** - For controlling lights via physical switches
2. **Motion Light Automations** - For motion-activated lighting
## Using the Module
To use this module in a system configuration:
```nix
{ config, ... }:
{
mjallen.services.home-assistant = {
enable = true;
# Optional: customize ports and device paths
mosquittoPort = 1883;
zigbee2mqttPort = 8080;
zigbeeDevicePath = "/dev/ttyUSB0";
};
}
```
## Extending the Module
### Adding Custom Components
To add a custom component:
1. Add the package to `packages/`
2. Add it to the `customComponents` list in `services/homeassistant/default.nix`
### Adding Custom Automations
To add a custom automation:
1. Create a new directory in `automations/`
2. Implement the automation in `default.nix`
3. Import it in the system configuration

23
docs/systems/README.md Normal file
View File

@@ -0,0 +1,23 @@
# System Configurations
This directory contains documentation for each system configuration in this repository.
## Systems
- [Desktop (matt-nixos)](./matt-nixos.md) - Main desktop computer
- [NAS (jallen-nas)](./jallen-nas.md) - Home server and NAS
- [NUC (nuc-nixos)](./nuc-nixos.md) - Intel NUC
- [Raspberry Pi 4](./pi4.md) - Raspberry Pi 4
- [Raspberry Pi 5](./pi5.md) - Raspberry Pi 5
- [MacBook Pro (nixOS)](./macbook-pro-nixos.md) - MacBook Pro running NixOS
## Common Configuration
All systems share certain common configurations through the modules system. These include:
- Base system configuration
- User management
- Network configuration
- Security settings
Each system then adds its specific configurations on top of these common modules.

101
docs/systems/jallen-nas.md Normal file
View File

@@ -0,0 +1,101 @@
# NAS Server (jallen-nas)
This document describes the configuration for the NAS server system.
## Hardware
The NAS server is built on AMD hardware:
- CPU: AMD processor
- Hardware-specific modules:
- `nixos-hardware.nixosModules.common-pc`
- `nixos-hardware.nixosModules.common-cpu-amd`
- `nixos-hardware.nixosModules.common-cpu-amd-pstate`
- `nixos-hardware.nixosModules.common-hidpi`
## Services
The NAS hosts various services:
### Media Services
- **Jellyfin** - Media server
- **Jellyseerr** - Media request manager
- **Sonarr** - TV show management
- **Radarr** - Movie management
- **Lidarr** - Music management
- **Bazarr** - Subtitle management
- **Music Assistant** - Music streaming integration with Home Assistant
### Download Services
- **Transmission** - Torrent client
- **NZBGet** - Usenet downloader
- **Prowlarr** - Indexer manager
### Document Management
- **Paperless-ngx** - Document management system
### File Sharing
- **Samba** - Windows file sharing
- **Nextcloud** - Self-hosted cloud storage
### AI Services
- **Ollama** - Local AI model hosting
### Smart Home
- **Home Assistant** - Smart home controller
- **Zigbee2MQTT** - Zigbee device integration
- **MQTT** - Message broker for IoT devices
- **Thread Border Router** - Thread network for smart home devices
## Storage Configuration
The NAS uses multiple storage devices:
1. **System Drive** - For the operating system
2. **Data Drives** - Configured as a storage array for media and data
## Network Configuration
The NAS is configured with:
- Static IP address
- Firewall rules for the various services
- Tailscale for secure remote access
## Backup Strategy
The NAS implements a comprehensive backup strategy:
1. **System Backup** - Regular backups of the NixOS configuration
2. **Data Backup** - Backups of important data to secondary storage
3. **Off-site Backup** - Critical data is backed up off-site
## Usage and Management
### Accessing Services
Most services are available through a reverse proxy, which provides:
- HTTPS access
- Authentication via Authentik
- Subdomain-based routing
### Adding Storage
To add additional storage to the NAS:
1. Add the physical drive to the system
2. Update the disko configuration
3. Rebuild the system with `nixos-rebuild switch`
### Monitoring
The system can be monitored through:
- Prometheus metrics
- Grafana dashboards
- Home Assistant sensors

213
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,213 @@
# Troubleshooting Guide
This guide provides solutions for common issues that may arise when using this NixOS configuration.
## System Issues
### Failed System Build
**Problem**: `nixos-rebuild switch` fails with an error.
**Solutions**:
1. **Syntax Errors**:
- Check the error message for file and line number information
- Verify the syntax in the mentioned file
- Common issues include missing semicolons, curly braces, or mismatched quotes
2. **Missing Dependencies**:
- If the error mentions a missing package or dependency:
```
git pull # Update to the latest version
nix flake update # Update the flake inputs
```
3. **Conflicting Modules**:
- Look for modules that might be configuring the same options incompatibly
- Disable one of the conflicting modules or adjust their configurations
4. **Disk Space Issues**:
- Check available disk space with `df -h`
- Clear old generations: `sudo nix-collect-garbage -d`
### Boot Issues
**Problem**: System fails to boot after a configuration change.
**Solutions**:
1. **Boot into a Previous Generation**:
- At the boot menu, select an older generation
- Once booted, revert the problematic change:
```
cd /etc/nixos
git revert HEAD # Or edit the files directly
sudo nixos-rebuild switch
```
2. **Boot from Installation Media**:
- Boot from a NixOS installation media
- Mount your system:
```
sudo mount /dev/disk/by-label/nixos /mnt
sudo mount /dev/disk/by-label/boot /mnt/boot # If separate boot partition
```
- Chroot into your system:
```
sudo nixos-enter --root /mnt
cd /etc/nixos
git revert HEAD # Or edit the files directly
nixos-rebuild switch --install-bootloader
```
## Home Assistant Issues
### Home Assistant Fails to Start
**Problem**: Home Assistant service fails to start.
**Solutions**:
1. **Check Service Status**:
```
systemctl status home-assistant
journalctl -u home-assistant -n 100
```
2. **Database Issues**:
- Check PostgreSQL is running: `systemctl status postgresql`
- Verify database connection settings in Home Assistant configuration
3. **Permission Issues**:
- Check ownership and permissions on config directory:
```
ls -la /var/lib/homeassistant
sudo chown -R hass:hass /var/lib/homeassistant
sudo chmod -R 750 /var/lib/homeassistant
```
4. **Custom Component Issues**:
- Try disabling custom components to isolate the issue:
- Edit `modules/nixos/homeassistant/services/homeassistant/default.nix`
- Comment out the `customComponents` section
- Rebuild: `sudo nixos-rebuild switch`
### Zigbee Device Connection Issues
**Problem**: Zigbee devices fail to connect or are unstable.
**Solutions**:
1. **Verify Device Path**:
- Check the Zigbee coordinator is properly detected:
```
ls -la /dev/ttyUSB*
```
- Update the device path if needed:
- Edit your system configuration
- Set `mjallen.services.home-assistant.zigbeeDevicePath` to the correct path
- Rebuild: `sudo nixos-rebuild switch`
2. **Interference Issues**:
- Move the Zigbee coordinator away from other wireless devices
- Try a USB extension cable to improve positioning
- Change Zigbee channel in Zigbee2MQTT configuration
3. **Reset Zigbee2MQTT**:
```
systemctl restart zigbee2mqtt
```
### Automation Issues
**Problem**: Automations don't run as expected.
**Solutions**:
1. **Check Automation Status**:
- In Home Assistant UI, verify the automation is enabled
- Check Home Assistant logs for automation execution errors
2. **Entity Issues**:
- Verify entity IDs are correct
- Check if entities are available/connected
- Test direct service calls to verify entity control works
3. **Trigger Issues**:
- Test the automation manually via Developer Tools > Services
- Use `automation.trigger` service with the automation's entity_id
## Flake Issues
### Flake Input Update Errors
**Problem**: `nix flake update` fails or causes issues.
**Solutions**:
1. **Selective Updates**:
- Update specific inputs instead of all at once:
```
nix flake lock --update-input nixpkgs
```
2. **Rollback Flake Lock**:
- If an update causes issues, revert to previous flake.lock:
```
git checkout HEAD^ -- flake.lock
```
3. **Pin to Specific Revisions**:
- In `flake.nix`, pin problematic inputs to specific revisions:
```nix
nixpkgs-stable.url = "github:NixOS/nixpkgs/5233fd2ba76a3accb05f88b08917450363be8899";
```
## Secret Management Issues
### Sops Decryption Errors
**Problem**: Sops fails to decrypt secrets.
**Solutions**:
1. **Key Issues**:
- Verify your GPG key is available and unlocked
- Check `.sops.yaml` includes your key fingerprint
2. **Permission Issues**:
- Check file permissions on secret files
- Make sure the user running `nixos-rebuild` has access to the GPG key
## Network Issues
### Firewall Blocks Services
**Problem**: Services are not accessible due to firewall rules.
**Solutions**:
1. **Check Firewall Status**:
```
sudo nix-shell -p iptables --run "iptables -L"
```
2. **Verify Firewall Configuration**:
- Check if ports are properly allowed in the configuration
- Add missing ports if necessary
3. **Temporary Disable Firewall** (for testing only):
```
sudo systemctl stop firewall
# After testing
sudo systemctl start firewall
```
## Getting Help
If you encounter an issue not covered in this guide:
1. Check the NixOS Wiki: https://nixos.wiki/
2. Search the NixOS Discourse forum: https://discourse.nixos.org/
3. Join the NixOS Matrix/Discord community for real-time help
4. File an issue in the repository if you believe you've found a bug

12
fountain_automation.yaml Normal file
View File

@@ -0,0 +1,12 @@
alias: "Fountain Cycle Mode"
description: "Toggles fountain water mode every 15 minutes between constant and intermittent flow"
trigger:
- platform: time_pattern
minutes: "/15" # Every 15 minutes
condition: []
action:
- service: select.select_next
target:
entity_id: select.dockstream_smart_rfid_fountain_water_dispensing_mode
mode: single
id: fountain_cycle_mode

View File

@@ -1,4 +1,4 @@
{ pkgs, namespace, ... }:
{ config, pkgs, namespace, ... }:
{
home = {
username = "admin";
@@ -6,6 +6,10 @@
with pkgs;
[
heroic
python3
python3Packages.requests
python3Packages.mcp
jq
]
++ (with pkgs.${namespace}; [
moondeck-buddy
@@ -52,6 +56,13 @@
};
programs = {
bash = {
shellAliases = {
"llama-status" =
"curl -s http://localhost:8127/health 2>/dev/null && echo 'LLaMA.cpp server is running' || echo 'LLaMA.cpp server is not responding'";
};
};
neovim = {
enable = true;
viAlias = true;
@@ -83,5 +94,75 @@
};
};
};
opencode = {
enable = true;
enableMcpIntegration = true;
settings = {
provider = {
nas = {
npm = "@ai-sdk/openai-compatible";
name = "llama-server (local)";
options = {
baseURL = "http://jallen-nas.local:8127/v1";
};
models = {
Qwen3-Coder-Next-Q4_0 = {
name = "Qwen3 Coder (local)";
modalities = {
input = [
"image"
"text"
];
output = [ "text" ];
};
limit = {
context = 262144;
output = 262144;
};
};
# "GLM-4.7-Flash-REAP-23B-A3B-UD-Q3_K_XL": {
# "name": "GLM 4.7 Flash (local)",
# "modalities": { "input": ["image", "text"], "output": ["text"] },
# "limit": {
# "context": 262144,
# "output": 262144
# }
# };
# "Nemotron-3-Nano-30B-A3B-IQ4_XS": {
# "name": "Nemotron-3-Nano (local)",
# "modalities": { "input": ["image", "text"], "output": ["text"] },
# "limit": {
# "context": 262144,
# "output": 262144
# }
# };
};
};
};
};
};
mcp = {
enable = true;
servers = {
nixos = {
command = "nix";
args = [
"run"
"github:utensils/mcp-nixos"
"--"
];
};
hass-mcp = {
command = "uvx";
args = [ "hass-mcp" ];
env = {
HA_URL = "http://nuc-nixos.local:8123";
HA_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI1ZDM2MTliNWNjMGY0ZGI2OWQzOTQ4Mjk0ZDFmNjAxMCIsImlhdCI6MTc3MDc2MjA1NywiZXhwIjoyMDg2MTIyMDU3fQ.P52jeX8GQcdGdzpbU3NCWZMUjkJZHFnOeR8--jy9dF8";
};
};
};
};
};
}

View File

@@ -7,12 +7,11 @@
}:
with lib;
let
name = "ai";
cfg = config.${namespace}.services.${name};
cfg = config.${namespace}.services.ai;
aiConfig = lib.${namespace}.mkModule {
inherit config name;
serviceName = "open-webui"; # todo multiple?
inherit config;
name = "ai";
description = "AI Services";
options = { };
moduleConfig = {
@@ -43,14 +42,25 @@ let
"--seed"
"3407"
"--temp"
"1.0"
"0.7"
"--top-p"
"0.95"
"0.9"
"--min-p"
"0.01"
"0.05"
"--top-k"
"40"
"30"
"--jinja"
"--ctx-size"
"4096"
"--threads"
"8"
"--batch-size"
"512"
"--gpu-layers"
"999"
"--flash-attn"
"auto"
"--mlock"
];
};
@@ -79,16 +89,52 @@ let
};
};
};
# Model update script using HuggingFace Hub
environment.systemPackages = with pkgs; [
amdgpu_top
python3Packages.huggingface-hub
];
# Systemd service for automatic model updates
systemd.services.update-qwen-model = {
description = "Update Qwen3-Coder-Next model from HuggingFace";
serviceConfig = {
Type = "oneshot";
ExecStart = "${pkgs.writeShellScript "update-qwen-model" ''
set -euo pipefail
MODEL_DIR="${cfg.configDir}/llama-cpp/models"
MODEL_NAME="Qwen3-Coder-Next-Q4_0.gguf"
REPO_ID="unsloth/Qwen3-Coder-Next-GGUF"
# Create model directory if it doesn't exist
mkdir -p "$MODEL_DIR"
# Download the latest version of the model
echo "Updating $MODEL_NAME from HuggingFace..."
${pkgs.python3Packages.huggingface-hub}/bin/huggingface-cli download \
"$REPO_ID" \
"$MODEL_NAME" \
--local-dir "$MODEL_DIR"
echo "Model updated successfully"
''}";
User = "nix-apps";
Group = "jallen-nas";
};
# Run daily at 3 AM
startAt = "*-*-* 03:00:00";
};
# Ensure model is available before llama-cpp starts
systemd.services.llama-cpp = {
after = [ "update-qwen-model.service" ];
wants = [ "update-qwen-model.service" ];
};
};
};
in
{
imports = [ aiConfig ];
config = lib.mkIf cfg.enable {
environment.systemPackages = with pkgs; [
amdgpu_top
python3Packages.huggingface-hub
];
};
}

315
scripts/README_tui.md Normal file
View File

@@ -0,0 +1,315 @@
# Version TUI Documentation
## Overview
The `version_tui.py` script is an interactive terminal interface for managing package versions in a NixOS repository. It provides a unified way to update version.json files, Python packages, and Home Assistant components.
## Architecture
### Core Components
1. **Package Discovery**: Scans the repository for different package types
2. **Version Management**: Handles version.json, Python default.nix, and Home Assistant components
3. **Hash Computation**: Uses modern Nix commands for reliable hash generation
4. **Interactive Interface**: Curses-based TUI with color support and keyboard navigation
## Package Types Supported
### 1. Regular Packages (`packages/**/version.json`)
- Standard version.json format with variables and sources
- Support for variants (base + overrides)
- Multiple fetcher types: github, git, url
### 2. Python Packages (`packages/python/*/default.nix`)
- Parses version, pname, and source info from default.nix
- Supports fetchFromGitHub and fetchPypi patterns
- Updates version, hash, tag, and rev fields
### 3. Home Assistant Components (`packages/homeassistant/*/default.nix`)
- Specialized parsing for HA component structure
- Handles domain, version, owner, and repo extraction
- GitHub-aware source management
## Fetcher Types
### GitHub Fetcher
```json
{
"fetcher": "github",
"owner": "owner",
"repo": "repo",
"tag": "v1.0.0",
"rev": "commit-hash",
"hash": "sha256-..."
}
```
### Git Fetcher
```json
{
"fetcher": "git",
"url": "https://github.com/user/repo.git",
"rev": "commit-hash",
"hash": "sha256-..."
}
```
### URL Fetcher
```json
{
"fetcher": "url",
"url": "https://example.com/file.tar.gz",
"hash": "sha256-..."
}
```
## Key Functions
### Hash Computation
#### `nix_prefetch_url(url: str)`
**Purpose**: Compute SHA256 SRI hash for URL sources
**Method**:
1. Try `nix store prefetch-file` (modern, SRI output)
2. Fallback to `nix-prefetch-url` (legacy, needs conversion)
3. Convert to SRI format if needed
#### `nix_prefetch_git(url: str, rev: str)`
**Purpose**: Compute SHA256 SRI hash for Git repositories
**Method**:
1. Use `nix eval` with `builtins.fetchGit` to get store path
2. Hash the store path with `nix hash path --type sha256`
3. Fallback to `nix-prefetch-git` if available
### API Functions
#### `gh_latest_release(owner, repo, token)`
- Gets latest release from GitHub API
- Returns tag_name of latest release
- Handles API errors gracefully
#### `gh_latest_tag(owner, repo, token)`
- Gets all tags and returns the first one
- Limited to 100 tags per page
- Sorts by GitHub's default ordering
#### `gh_head_commit(owner, repo)`
- Uses `git ls-remote` to get HEAD commit
- No API token required
- Fallback for when GitHub API fails
### Special Cases
#### Raspberry Pi Linux
- Prefers `stable_YYYYMMDD` tags over latest
- Falls back to series-specific tags (`rpi-X.Y`)
- Maintains compatibility with existing tagging schemes
#### CachyOS Linux
- Fetches latest version from upstream PKGBUILD
- Supports different suffixes (rc, hardened, lts)
- Handles both .SRCINFO and PKGBUILD parsing
## UI Navigation
### Main Package List
```
↑/k/j : Navigate up/down
g/G : Go to top/bottom
Enter : Open package details
f : Cycle filters (all → regular → python → all)
q/ESC : Quit
```
### Package Details Screen
```
←/h/l : Switch variants (if available)
↑/k/j : Navigate sources
r : Refresh candidates
h : Recompute hash
e : Edit field (path=value)
s : Save changes
i : Show full URL (URL sources)
Enter : Action menu for selected source
Backspace : Return to package list
q/ESC : Quit
```
### Action Menu
```
↑/k/j : Select option
Enter : Execute selected action
Backspace : Cancel
```
## File Structure Analysis
### version.json Format
```json
{
"schemaVersion": 1,
"variables": {
"key": "value"
},
"sources": {
"name": {
"fetcher": "type",
"...": "..."
}
},
"variants": {
"variant-name": {
"sources": {
"name": {
"override": "value"
}
}
}
}
}
```
### Python Package Parsing
The script extracts information from patterns like:
```nix
{
pname = "package-name";
version = "1.0.0";
src = fetchFromGitHub {
owner = "user";
repo = "repo";
rev = "v1.0.0";
sha256 = "...";
};
}
```
### Home Assistant Component Parsing
```nix
{
domain = "component_name";
version = "1.0.0";
src = fetchFromGitHub {
owner = "user";
repo = "repo";
rev = "v1.0.0";
sha256 = "...";
};
}
```
## Error Handling
### Network Errors
- Timeouts: 10-second timeout on HTTP requests
- HTTP status codes: Proper handling of 4xx/5xx responses
- Retry logic: Graceful fallback when APIs fail
### API Rate Limiting
- Uses `GITHUB_TOKEN` environment variable if available
- Provides clear error messages when rate limited
- Falls back to git commands when API fails
### Git Command Failures
- Robust error handling for git ls-remote
- Validation of git command output
- Clear error messages for debugging
## Configuration
### Environment Variables
- `GITHUB_TOKEN`: GitHub personal access token (optional)
- Increases API rate limits from 60/hour to 5000/hour
### Dependencies
- **Required**: `nix` command with experimental features
- **Optional**: `nix-prefetch-git`, `git` commands
- **Python**: Standard library + curses
## Troubleshooting
### Hash Mismatches
1. Check if using correct Nix version
2. Verify network connectivity to GitHub
3. Try manual hash computation:
```bash
nix store prefetch-file --hash-type sha256 <url>
```
### Missing Candidates
1. Check GitHub token availability
2. Verify repository exists and is accessible
3. Check network connectivity
4. Try manual API calls with curl
### Display Issues
1. Ensure terminal supports colors and Unicode
2. Check terminal size (minimum 80x24 recommended)
3. Try resizing terminal window
4. Use `-r` flag to force redraw
## Development
### Adding New Fetcher Types
1. Update `fetch_candidates_for()` method
2. Add parsing logic to appropriate `parse_*()` function
3. Update hash computation methods
4. Add UI handling for new type
### Testing Changes
```bash
# Test individual functions
python3 -c "
from scripts.version_tui import nix_prefetch_url
print(nix_prefetch_url('https://example.com/file.tar.gz'))
"
# Test package parsing
python3 -c "
from scripts.version_tui import parse_python_package
print(parse_python_package(Path('packages/python/example/default.nix')))
"
```
## Architecture Decisions
### Why Multiple Hash Methods?
- Different Nix versions have different available commands
- Modern Nix uses `nix store prefetch-file` and `nix eval`
- Legacy systems use `nix-prefetch-url` and `nix-prefetch-git`
- Script tries modern methods first, falls back gracefully
### Why Template Rendering?
- Variables allow flexible version specifications
- Supports `${variable}` substitution in URLs and tags
- Enables consistent updates across variants
- Reduces duplication in version.json files
### Why Two-Step Git Hash?
- `builtins.fetchGit` provides store paths, not hashes
- `nix hash path` works reliably on store paths
- More consistent than trying to parse git command output
- Works with all git repository formats
## File Organization
```
scripts/
├── version_tui.py # Main script
├── __pycache__/ # Python cache
└── README_tui.md # This documentation
```
## Security Considerations
- No sensitive data is logged
- GitHub tokens are handled securely via environment
- Hash computation uses read-only operations
- No credentials are stored or transmitted unnecessarily
## Performance
- Lazy loading of candidates (only when needed)
- Caching of computed hashes during session
- Parallel network requests where possible
- Efficient terminal rendering with minimal refreshes

File diff suppressed because it is too large Load Diff

View File

@@ -16,7 +16,9 @@ in
createUser = true;
reverseProxy = enabled;
};
ai = enabled;
ai = {
enable = true;
};
arrs = {
enable = true;
enableVpn = true;