Nicolas Duhamel
f82a913bdd
- Add centralized configuration system with backup.env - Move configuration files to proper structure (config/ directory) - Remove hardcoded paths and make system portable - Fix security issue: remove password exposure in gen-conf.sh - Add comprehensive documentation (README.md, CLAUDE.md) - Create configuration template (backup.env.sample) - Add .gitignore to protect sensitive files - Update all scripts to use environment variables - Implement systemd template variable substitution 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
# 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:**
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
source backup.env
|
|
./backup/list-snapshots [service] # List available snapshots
|
|
./backup/restore <service> --test # Test restoration
|
|
./backup/restore <service> --production # Production restoration
|
|
```
|
|
|
|
### Configuration Testing
|
|
```bash
|
|
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:
|
|
```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
|
|
- `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 |