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:**

```bash
# 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
```bash
cp backup.env.sample backup.env  # Copy configuration template
# Edit backup.env to match environment
./install                         # Complete installation (config + repository)
```

### Service Management
```bash
./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
```bash
./manage snapshots [service]     # List available snapshots
./manage restore <service>       # Test restoration
./manage restore-prod <service>  # Production restoration
```

### Configuration Testing
```bash
# 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:
```bash
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:
   ```bash
   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