Backups

The Backup system in Kinesis API provides automated backup and restore functionality for your database and configuration files. This built-in feature allows you to create, manage, and restore backups directly through the web interface or API, ensuring your data is protected and recoverable.

Overview

The backup system serves as a comprehensive data protection solution for:

• Creating point-in-time snapshots of your entire database
• Scheduling automatic backups with expiration dates
• Restoring your system to a previous state
• Managing backup storage and retention policies

All backups are stored as compressed archives containing your database files, ensuring efficient storage while maintaining data integrity.

Key Features

Automated Backup Creation

• One-Click Backups: Create full system backups instantly through the web interface
• Compressed Storage: Backups are automatically compressed to save storage space
• Complete Coverage: Includes all database files (pages, blobs, and indexes)
• Metadata Tracking: Each backup includes creation time, description, and expiry information

Backup Management

• Descriptive Labels: Add custom descriptions to identify backup purposes
• Expiration Dates: Set automatic expiration to manage storage space
• Filtering and Search: Find specific backups quickly through search functionality
• Bulk Operations: Manage multiple backups efficiently

Restore Functionality

• Full System Restore: Restore your entire database from any backup
• Engine Reset: Automatically reloads the database engine after restoration
• Data Integrity: Maintains all relationships and constraints during restoration

Storage and Retention

• Automatic Cleanup: Expired backups are automatically removed
• Storage Optimization: TAR.GZ compression reduces backup file sizes
• Secure Storage: Backups are stored in a dedicated, protected directory

User Permissions

Backup functionality requires ROOT privileges:

ROOT Users

• Create new backups
• View all existing backups
• Restore from any backup
• Delete backup files
• Manage backup descriptions and expiry dates

Other User Roles

• No access to backup functionality (security restriction)

Using the Backup Management Interface

The backup management interface provides comprehensive control over your backup operations:

Accessing Backup Management

1. Log in with a ROOT account
2. Navigate to /web/backups in your browser or select "Backups" from the sidebar menu

Creating a New Backup

To create a backup:

1. Click the "Create a new backup" button
2. Add an optional description to identify the backup purpose
3. Set an optional expiry date for automatic cleanup
4. Click "Create" to start the backup process

The system will:

• Create a compressed archive of all database files
• Store the backup with a timestamp-based filename
• Add the backup record to the management interface

Viewing Backup Information

Each backup in the list displays:

• Backup Name: Auto-generated filename with timestamp and ID
• Creation Date: When the backup was created
• Description: Custom description (if provided)
• Expiry Date: When the backup will automatically expire (if set)

Managing Existing Backups

For each backup, you can:

Update Description

1. Click the "Description" link next to any backup
2. Edit the description text
3. Click "Submit" to save changes

Update Expiry Date

1. Click the "Expiry" link next to any backup
2. Set a new expiry date/time or clear to remove expiration
3. Click "Submit" to save changes

Restore from Backup

1. Click the restore button (refresh icon) next to any backup
2. Confirm the restoration in the warning dialog
3. The system will restore all data and restart the database engine

⚠️ Warning: Restoring a backup will replace all current data with the backup data. This action cannot be undone.

Delete Backup

1. Click the delete button (trash icon) next to any backup
2. Confirm the deletion in the warning dialog
3. The backup file and record will be permanently removed

Filtering and Searching

To find specific backups:

1. Use the search bar to filter by backup name or description
2. The list will automatically update to show matching backups
3. Pagination controls help navigate through large backup collections

Backup File Structure

Backups are stored as TAR.GZ archives containing:

• Configuration Files (.env): System configuration and environment variables
• Database Pages (data/main_db.pages): Core database structure and data
• Blob Storage (data/main_db.blobs): Large string data storage
• Blob Index (data/main_db.blobs.idx): Blob storage index for quick access
• Public Directory (public/): User-uploaded media files and assets
• Translations Directory (translations/): Localization files and language packs

The backup filename format is:

backup-[YYYYMMDD_HHMM]_[backup_id].tar.gz

For example: backup-20250804_1430_15.tar.gz

Automatic Cleanup

The backup system includes automatic maintenance:

Expiry Processing

• Expired backups are automatically identified and removed
• This happens whenever backup operations are performed
• Both the database record and the physical file are cleaned up

Storage Management

• Only necessary database files are included in backups
• TAR.GZ compression reduces storage requirements
• Automatic cleanup prevents unlimited storage growth

API Integration

The backup system can also be accessed programmatically through the REST API:

Create Backup

POST /backup/create
Authorization: Bearer [token]
Content-Type: application/json

{
  "uid": 1,
  "backup": {
    "description": "Pre-deployment backup",
    "expiry": "2025-12-31T23:59:59+00:00"
  }
}

Restore Backup

GET /backup/restore?uid=1&id=15
Authorization: Bearer [token]

List Backups

GET /backup/fetch?uid=1&limit=50&offset=0
Authorization: Bearer [token]

Best Practices

For effective backup management:

Regular Backup Schedule

• Create backups before major system changes
• Establish a regular backup routine (daily/weekly)
• Use descriptive names to identify backup purposes

Retention Strategy

• Set appropriate expiry dates to manage storage
• Keep recent backups for quick recovery
• Archive important milestones for longer-term retention

Testing and Verification

• Periodically test restore procedures
• Verify backup integrity by checking file sizes and dates
• Document your backup and restore procedures

Security Considerations

• Limit backup access to ROOT users only
• Monitor backup creation and restoration activities
• Consider backing up the backup directory to external storage

Restoration Process

When restoring from a backup:

1. System Shutdown: Current database operations are suspended
2. File Replacement: Database files are replaced with backup versions
3. Engine Restart: The database engine is reloaded with restored data
4. Validation: System verifies the restoration was successful

This process ensures complete data consistency and system integrity after restoration.

Backup Scheduling

Kinesis API's scheduling feature allows you to automate the backup process with precise timing control using cron-style expressions.

Understanding Backup Schedules

Backup schedules provide:

• Automated Creation: Backups run automatically on your defined schedule
• Flexible Timing: From hourly to monthly schedules using cron expressions
• Expiration Control: Set how long scheduled backups should be retained
• Resource Optimization: Only create backups when needed

Accessing Backup Scheduling

1. Log in with a ROOT account
2. Navigate to /web/backups/schedules or select "Backup Schedules" from the Backups submenu

Creating a Backup Schedule

To create a schedule:

1. Click the "Create a new backup schedule" button
2. Fill in the schedule details:
   • Name: A descriptive name (e.g., "Daily Midnight Backup")
   • Schedule: Configure the cron expression components
   • Expiry Hours: How long (in hours) to keep backups created by this schedule
   • Enabled: Toggle to activate/deactivate the schedule
3. Click "Create" to save and activate the schedule

Understanding Cron Expressions

Backup schedules use standard cron expressions with five fields:

* * * * *  command to be executed
- - - - -
| | | | |
| | | | +----- Day of the week (0 - 6) (Sunday is 0)
| | | +------- Month (1 - 12)
| | +--------- Day of the month (1 - 31)
| +----------- Hour (0 - 23)
+------------- Min (0 - 59)

Examples

• 0 * * * *: At minute 0 past every hour
• 30 1 * * *: At 01:30 AM every day
• 0 0 * * 0: At midnight on Sundays
• 15 14 1 * *: At 14:15 on the first day of every month

Managing Backup Schedules

For each schedule, you can:

Update Schedule

1. Click the "Edit" button next to any schedule
2. Modify the schedule details
3. Click "Save" to apply changes

Delete Schedule

1. Click the delete button (trash icon) next to any schedule
2. Confirm the deletion in the warning dialog
3. The schedule will be permanently removed

Monitoring Scheduled Backups

Scheduled backups are listed with:

• Schedule Name: Descriptive name of the schedule
• Next Run: When the backup will next run
• Expiry: How long backups are retained
• Status: Enabled or disabled state

Troubleshooting

Common Issues

Backup Creation Failed

• Check available disk space
• Verify database file permissions
• Ensure the backups directory exists and is writable

Restoration Failed

• Verify the backup file exists and isn't corrupted
• Check that the backup contains all required database files
• Ensure sufficient disk space for restoration

Missing Backups

• Check if backups have expired and been automatically cleaned up
• Verify backup directory location and permissions
• Look for backup files in the correct directory

Scheduled Backup Not Running

• Check if the schedule is enabled
• Verify the cron expression is correct
• Ensure the system time is correct

Backup Files Not Expiring

• Check the expiry hours setting for the schedule
• Verify that the cleanup process is running
• Ensure there are no permission issues with the backup files