77 lines
No EOL
3.3 KiB
Markdown
77 lines
No EOL
3.3 KiB
Markdown
# 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 |