citadel/CLAUDE.md

CLAUDE.md

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

Critical Convention

ALL scripts must be executed in an environment that has sourced the configuration:

# Always start by sourcing configuration
source backup.env

# Then execute any script
./backup/manage list
./backup/gen-conf.sh
sudo ./backup/install-service paperless

This is the core architectural pattern of this codebase. Scripts do NOT auto-source configuration files.

Common Commands

Initial Setup

cp backup.env.sample backup.env  # Copy configuration template
# Edit backup.env to match environment
source backup.env
./backup/gen-conf.sh          # Generate secure Restic configuration
./backup/init-restic.sh       # Initialize Restic repository

Service Management

source backup.env
./backup/manage list                    # List all backup timers
./backup/manage status <service>        # Service backup status
./backup/manage run <service>           # Manual backup execution
./backup/manage logs <service>          # View backup logs
sudo ./backup/install-service <service> # Install systemd timer

Backup Operations

source backup.env
./backup/list-snapshots [service]                # List available snapshots
./backup/restore <service> --test                # Test restoration
./backup/restore <service> --production          # Production restoration

Configuration Testing

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

• backup/manage: Primary interface for all backup operations and service management
• backup/install-service: Systemd timer installer that performs variable substitution in templates
• backup/restore: Advanced restoration tool with test/production modes and safety checks
• 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

• backup/manage: Main interface (list, status, run, logs commands)
• backup/gen-conf.sh: Secure configuration generator
• backup/init-restic.sh: Repository initialization
• backup/install-service: Systemd timer installation with template substitution

Templates and Restoration

• backup/service-backup@.{service,timer}: Systemd unit templates with variable placeholders
• backup/restore: Production-grade restoration with test mode and extensive validation
• backup/list-snapshots: Snapshot browsing utility

Development Guidelines

When adding new scripts:

1. Add comment: # Configuration should be sourced before running: source backup.env
2. Use variables from backup.env directly (do not auto-source)
3. Follow the pattern of existing scripts for error handling and logging
4. For systemd integration, use template substitution pattern from install-service

When modifying configuration:

• 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