Hetzner-Backup/CLAUDE.md

CRITICAL RULES - ALWAYS FOLLOW

1. BACKUP BEFORE ANY CHANGES

MANDATORY: Create backup before ANY code changes:

./create_full_backup.sh

• Creates full server backup and pushes to GitHub automatically
• Local copy remains for quick rollback
• Restore if needed: ./restore_full_backup.sh server_backup_YYYYMMDD_HHMMSS

2. GITHUB BACKUPS ARE PERMANENT

• NEVER DELETE backups from GitHub repository (hetzner-backup)
• Only local backups can be deleted after successful upload
• GitHub serves as permanent backup archive

3. BACKUP TROUBLESHOOTING

If create_full_backup.sh fails to push:

• SSH key configured at: ~/.ssh/github_backup
• Fix "Author identity unknown": git -c user.email="backup@intelsight.de" -c user.name="Backup System" commit -m "..."
• Repository: git@github.com:UserIsMH/hetzner-backup.git

4. BACKUP SCHEDULE

• Manual backups: Before EVERY change using ./create_full_backup.sh
• Automatic backups: Daily at 3:00 AM via Admin Panel
• Admin Panel backup interface: https://admin-panel-undso.intelsight.de/backups

SYSTEM OVERVIEW

Production license management system at intelsight.de with:

• Admin Panel (Flask): Web interface for customer/license/resource management
• License Server (FastAPI): API for license validation and heartbeat monitoring
• PostgreSQL: Database with partitioned tables for performance
• Nginx: SSL termination and routing

KEY FEATURES

1. License Management

• Device Limit: Each license has a device_limit (1-10 devices)
• Concurrent Sessions: Each license has a concurrent_sessions_limit (max simultaneous users)
• Constraint: concurrent_sessions_limit ≤ device_limit
• Resource Allocation: Domains, IPv4 addresses, phone numbers per license

2. Device Management

• Single Table: device_registrations stores all device information
• Device Fields: hardware_fingerprint (unique ID), device_name, device_type
• Tracking: First activation, last seen, active status
• No automatic termination: When session limit reached, new sessions are denied

3. Authentication & Security

• API Authentication: X-API-Key header (format: AF-YYYY-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)
• API Key Management: Admin Panel → "Lizenzserver Administration" → "System-API-Key generieren"
• 2FA Support: TOTP-based two-factor authentication for admin users
• Audit Logging: All changes tracked in audit_log table

4. Session Management

• Heartbeat: 30-second intervals (configurable)
• Timeout: 60 seconds without heartbeat = automatic cleanup
• Single Device Resume: Same device can resume existing session
• Session Token: UUID v4 for session identification

5. Database Structure

• Partitioned Tables: license_heartbeats (monthly partitions)
• Resource Pools: Centralized management of domains/IPs/phones
• Session History: Complete tracking with end reasons
• Lead CRM: Institution and contact management system