Lucas/Homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Homelab/CLAUDE.md
Lucas Thelen e08c4b27e2 Extensible DDNS
2025-10-03 18:13:26 +00:00

2.6 KiB
Raw Blame History

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 - Default NixOS configuration (mostly commented out)
  • system.nix - System-level settings (boot, power management)
  • packages.nix - System packages (neovim, git, tools)
  • users.nix - User configuration for lucas user with fish shell

Modular Organization

  • 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
  • services/ - Service modules
    • jellyfin.nix - Media server with Deluge torrent client
    • site.nix - Nginx reverse proxy, ACME SSL, Route53 DDNS

Secret Management

  • Uses agenix for encrypted secrets
  • secrets/aws.age - AWS credentials for Route53 updates
  • 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
  • Multimedia group for media file permissions at /data/media
  • Fish shell is the default for the lucas user
  • ACME certificates automatically managed for per-aspera.space domain