citadel/CLAUDE.md

CLAUDE.md

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

Critical Convention

Use the unified interface scripts that auto-source configuration:

# Installation and setup
./install           # Complete setup (config + repository)  
./install config    # Generate configuration only
./install repo      # Initialize repository only

# All backup operations via manage
./manage list                    # List backup timers
./manage install <service>       # Install service timer  
./manage run <service>           # Manual backup
./manage restore <service>       # Restore (test mode)
./manage restore-prod <service>  # Restore (production)

NEVER call scripts in backup/ directly - they are protected and will error. Always use ./manage or ./install.

Common Commands

Initial Setup

cp backup.env.sample backup.env  # Copy configuration template
# Edit backup.env to match environment
./install                         # Complete installation (config + repository)

Service Management

./manage list                    # List all backup timers
./manage status <service>        # Service backup status  
./manage run <service>           # Manual backup execution
./manage logs <service>          # View backup logs
./manage available               # List services with backup.sh
sudo ./manage install <service>  # Install systemd timer

Backup Operations

./manage snapshots [service]     # List available snapshots
./manage restore <service>       # Test restoration
./manage restore-prod <service>  # Production restoration

Configuration Testing

# Source configuration manually for utility functions
source backup.env
show_config                   # Display current configuration
validate_paths               # Check directory existence

Architecture

Configuration System

• backup.env: Master configuration file at project root containing all environment variables
• config/restic.conf: Generated Restic-specific configuration (created by gen-conf.sh)
• Variable substitution: systemd templates use ${VAR} placeholders replaced during installation

Core Components

• ./manage: Primary interface for all backup operations and service management (auto-sources config)
• ./install: Installation script consolidating configuration generation and repository initialization
• backup/install-service: Systemd timer installer (called via ./manage install)
• backup/restore: Advanced restoration tool (called via ./manage restore/restore-prod)
• Templates: service-backup@.service and service-backup@.timer are systemd unit templates

Variable Override Pattern

Configuration uses environment variable defaults with override capability:

BACKUP_USER="${BACKUP_USER:-citadel}"
PROJECT_ROOT="${PROJECT_ROOT:-/home/nicolas/dev/quantumrick}"

Users can customize by setting environment variables before sourcing backup.env.

Systemd Integration

• Templates in backup/ directory contain ${VARIABLE} placeholders
• install-service script performs sed substitution to generate final systemd units
• Generated units placed in /etc/systemd/system/ with proper permissions

Security Model

• Restic passwords auto-generated with OpenSSL
• Configuration files have restricted permissions (600)
• Scripts validate directory existence before operations
• Restoration includes test mode for safety

Key Files and Their Roles

Configuration Layer

• backup.env: Master configuration with all variables and utility functions
• config/restic.conf: Generated Restic authentication and repository settings

Operational Scripts

• ./manage: Main interface (list, status, run, logs commands) - auto-sources configuration
• ./install: Consolidated installation script (config + repository)
• backup/install-service: Systemd timer installation with template substitution
• backup/list-snapshots: Snapshot browsing utility
• backup/restore: Production-grade restoration tool

Templates and Restoration

• backup/service-backup@.{service,timer}: Systemd unit templates with variable placeholders

Development Guidelines

Script Protection

All scripts in backup/ are protected against direct execution:

• Use CALLED_FROM_MANAGE environment variable check
• Scripts error with helpful message if called directly
• Always route through ./manage interface

Adding New Scripts

1. If adding scripts to backup/, include protection check:

   if [ "${CALLED_FROM_MANAGE:-}" != "true" ]; then
       echo "ERROR: Use ./manage <command> instead"
       exit 1
   fi
   

2. Add corresponding command to ./manage with CALLED_FROM_MANAGE=true
3. Follow existing error handling and logging patterns

Configuration Changes

• All path variables should have environment override capability
• Maintain backward compatibility with default values
• Update both backup.env and this documentation if adding new variables
• Test with both ./manage and ./install interfaces