CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a NixOS homelab configuration using Nix flakes. The setup includes a self-hosted Jellyfin media server, personal website hosting, VPN access via Tailscale, and automated DNS management with AWS Route53.

Development Commands

System Management

sudo nixos-rebuild switch --flake .#homelab - Apply configuration changes
sudo nixos-rebuild test --flake .#homelab - Test configuration without making it default
nix flake update - Update flake inputs (updates flake.lock)
nixfmt-classic *.nix - Format Nix files using the installed formatter

Git Operations

Configuration is version controlled - commit changes after testing
Current branch: main
Modified files: flake.nix, users.nix (check git status)

Architecture

Flake Structure

flake.nix - Main flake definition with inputs (nixpkgs, agenix, personal site)
configuration.nix - Legacy configuration (minimal, contains system.stateVersion)

Modular Organization

config/ - Shared configuration options
- common.nix - Common options used across modules (domain, user, networking, etc.)
modules/core/ - Core system functionality
- boot.nix - Boot loader and Nix settings
- server-power.nix - Server power management (disable sleep/hibernation)
- packages.nix - System packages (neovim, git, tools)
modules/hardware/ - Hardware-specific configurations
- hardware-configuration.nix - Hardware scan results
modules/users/ - User management
- lucas.nix - User configuration with fish shell and multimedia group
modules/networking/ - Network configuration modules
- host.nix - Static IP, firewall, Avahi discovery
- ssh.nix - SSH daemon configuration
- adblock.nix - Ad blocking setup
- vpn-host.nix - Tailscale VPN with auto-connect
modules/services/ - Service modules
- jellyfin.nix - Media server with Deluge torrent client
- site.nix - Nginx reverse proxy, ACME SSL, Route53 DDNS
- forgejo.nix - Git server
- calibre-web.nix - Ebook server

Secret Management

Uses agenix for encrypted secrets
secrets/aws.age - AWS credentials for Route53 updates
secrets/tailscale.age - Tailscale authentication key

Key Services

Jellyfin: Media server on port 8096, proxied via jellyfin.per-aspera.space
Personal Website: Static site from GitHub repo served at per-aspera.space
Deluge: Torrent client with web interface
Route53 DDNS: Automated IP updates every 5 minutes
Tailscale: VPN access with firewall rules

Network Configuration

Static IP: 192.168.0.10/24
Hostname: homelab
Firewall: Configured per service (HTTP/HTTPS, Jellyfin, SSH via Tailscale)
Custom nameservers: 205.171.3.25, 8.8.8.8

Important Notes

System is configured as a server (no hibernation/suspend)
Uses systemd-boot EFI bootloader
Modular configuration with shared options in config/common.nix
Decoupled modules reduce hard-coded dependencies
Fish shell is the default for the lucas user
ACME certificates automatically managed for per-aspera.space domain
Use nix flake check and nix flake build to test building without having to do nixos-rebuild
New files will need to be tracked by git add to be able to be used by nix flakes

3.3 KiB Raw Blame History