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) for executing backups, cleanup, and monitoring
• A Flask web GUI (tisbackup_gui.py) for managing backups
• A pluggable backup driver architecture in libtisbackup/
• Task queue system using Huey with Redis (tasks.py, config.py)
• Docker-based deployment with cron scheduling

Development Commands

Dependency Management

# Install dependencies (uses uv)
uv sync --locked

# Update dependencies
uv lock

Linting

# Run ruff linter
ruff check .

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

Running the Application

Web GUI (development):

python3 tisbackup_gui.py
# Runs on port 8080, requires config at /etc/tis/tisbackup_gui.ini

CLI Commands:

# 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

# 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 - CLI application with argument parsing and action routing (backup, cleanup, checknagios, etc.)
• tisbackup_gui.py - Flask web application providing UI for backup management and status monitoring
• tasks.py - Huey task definitions for async operations (export_backup)

Backup Driver System:

All backup logic is implemented via driver classes in libtisbackup/:

• Base class: backup_generic in common.py (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 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 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/
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

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}/