TISbackup/CLAUDE.md

# CLAUDE.md

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

## Project Overview

TISBackup is a server-side backup orchestration system written in Python. It executes scheduled backups of various data sources (databases, files, VMs) from remote Linux and Windows systems. The project consists of:

- A CLI tool ([tisbackup.py](tisbackup.py)) for executing backups, cleanup, and monitoring
- A Flask web GUI ([tisbackup_gui.py](tisbackup_gui.py)) for managing backups
- A pluggable backup driver architecture in [libtisbackup/](libtisbackup/)
- Task queue system using Huey with Redis ([tasks.py](tasks.py), [config.py](config.py))
- Docker-based deployment with cron scheduling

## Development Commands

### Dependency Management
```bash
# Install dependencies (uses uv)
uv sync --locked

# Update dependencies
uv lock
```

### Linting
```bash
# Run ruff linter
ruff check .

# Auto-fix linting issues
ruff check --fix .
```

### Running the Application

**Web GUI (development):**
```bash
python3 tisbackup_gui.py
# Runs on port 8080, requires config at /etc/tis/tisbackup_gui.ini
```

**CLI Commands:**
```bash
# Run backups
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini backup

# Run specific backup section
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini -s section_name backup

# Cleanup old backups
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini cleanup

# Check backup status (for Nagios)
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini checknagios

# List available backup drivers
python3 tisbackup.py listdrivers
```

### Docker

```bash
# Build image
docker build . -t tisbackup:latest

# Run via docker compose (see README.md for full setup)
docker compose up -d
```

## Architecture

### Core Components

**Main Entry Points:**
- [tisbackup.py](tisbackup.py) - CLI application with argument parsing and action routing (backup, cleanup, checknagios, etc.)
- [tisbackup_gui.py](tisbackup_gui.py) - Flask web application providing UI for backup management and status monitoring
- [tasks.py](tasks.py) - Huey task definitions for async operations (export_backup)

**Backup Driver System:**

All backup logic is implemented via driver classes in [libtisbackup/](libtisbackup/):

- Base class: `backup_generic` in [common.py](libtisbackup/common.py:565) (abstract)
- Each driver inherits from `backup_generic` and implements specific backup logic
- Drivers are registered via the `register_driver()` decorator function
- Configuration is read from INI files using the `read_config()` method

**Available Drivers:**
- `backup_rsync` / `backup_rsync_ssh` - File-based backups via rsync
- `backup_rsync_btrfs` / `backup_rsync__btrfs_ssh` - Btrfs snapshot-based backups
- `backup_mysql` - MySQL database dumps
- `backup_pgsql` - PostgreSQL database dumps
- `backup_oracle` - Oracle database backups
- `backup_sqlserver` - SQL Server backups
- `backup_samba4` - Samba4 AD backups
- `backup_xva` / `backup_xcp_metadata` - XenServer VM backups
- `backup_vmdk` - VMware VMDK backups
- `backup_switch` - Network switch configuration backups
- `backup_null` - No-op driver for testing

**State Management:**
- SQLite database tracks backup history, status, and statistics
- `BackupStat` class in [common.py](libtisbackup/common.py) handles DB operations
- Database location: `{backup_base_dir}/log/tisbackup.sqlite`

### Configuration

Two separate INI configuration files:

1. **tisbackup-config.ini** - Backup definitions
   - `[global]` section with defaults (backup_base_dir, backup_retention_time, maximum_backup_age)
   - One section per backup job with driver type and parameters

2. **tisbackup_gui.ini** - GUI settings
   - Points to tisbackup-config.ini location(s)
   - Defines admin email, base directories

### Task Queue

- Uses Huey (Redis-backed) for async job processing
- Currently implements `run_export_backup` for exporting backups to external storage
- Task state tracked in tasks.sqlite

### Docker Deployment

Two-container architecture:
- **tisbackup_gui**: Runs Flask web interface
- **tisbackup_cron**: Runs scheduled backups via cron (executes [backup.sh](backup.sh) at 03:59 daily)

## Code Style

- Line length: 140 characters (configured in pyproject.toml)
- Ruff ignores: F401, F403, F405, E402, E701, E722, E741
- Python 3.13+ required

## Important Patterns

**Adding a new backup driver:**
1. Create `backup_<type>.py` in [libtisbackup/](libtisbackup/)
2. Inherit from `backup_generic`
3. Set class attributes: `type`, `required_params`, `optional_params`
4. Implement abstract methods: `do_backup()`, `cleanup()`, `checknagios()`
5. Register with `register_driver(backup_<type>)`
6. Import in [tisbackup.py](tisbackup.py)

**SSH Operations:**
- Uses paramiko for SSH connections
- Supports both RSA and DSA keys
- Private key path specified per backup section via `private_key` parameter
- Pre/post-exec hooks run remote commands via SSH

**Path Handling:**
- Module imports use sys.path manipulation to include lib/ and libtisbackup/
- All backup drivers expect absolute paths for backup_dir
- Backup directory structure: `{backup_base_dir}/{section_name}/{timestamp}/`