Backups

Regular backups are a critical component of maintaining a reliable Kinesis API installation. This guide covers how to properly back up your Kinesis API data and configuration, ensuring you can recover from unexpected failures or data corruption.

Backup Methods

Kinesis API offers multiple backup approaches to suit different needs and technical preferences:

1. Built-in Backup System (Recommended)

New in version 0.31.0: Kinesis API now includes a comprehensive backup system accessible through the web interface and API. This is the recommended method for most users as it provides:

Automated backup creation and management
Built-in compression and storage optimization
Integrated restore functionality
Expiration and retention management
User-friendly web interface

Getting Started:

Log in to your Kinesis API web interface as a ROOT user
Navigate to the "Backups" section in the sidebar
Click "Create a new backup" to generate your first backup

For detailed instructions on using the built-in backup system, see the Backup Management page.

Benefits:

No manual file handling required
Automatic compression reduces storage space
Built-in validation ensures backup integrity
Simple restore process with automatic engine restart
Integrated with the permission system for security

2. Manual File-Based Backup

For users who prefer direct file system control or need custom backup procedures:

Understanding Kinesis API's Data Storage

Before discussing backup strategies, it's important to understand where Kinesis API stores its data:

Database Files: Located in the data/ directory
Configuration: Stored in the .env file
Media Files: Stored in the public/ directory
Translations: Stored in the translations/ directory

A complete backup must include all three components to ensure full recovery.

Manual Backup Methods

Docker Installation Backup:

If you're running Kinesis API via Docker (the recommended method), follow these steps:

Stop the container (optional but recommended for consistency):
```
docker stop kinesis-api
```
Create the backup directory:
```
mkdir backup/
```
Back up the data directory:
```
cp -r data/ backup/data/
```
Back up the environment file:
```
cp .env backup/.env
```
Back up the public directory (if you've uploaded media):
```
cp -r public/ backup/public/
```
Back up the translations directory (if you're making use of the localization engine):
```
cp -r translations/ backup/translations/
```
Restart the container (if you stopped it):
```
docker start kinesis-api
```

Native Installation Backup:

If you're running Kinesis API directly on your host:

Stop the Kinesis API service:

# If using systemd
sudo systemctl stop kinesis-api

# Or if running directly
kill $(pgrep kinesis-api)

Back up the required directories and files:

cp -r /path/to/kinesis-api/data/ /path/to/backup/data/
cp /path/to/kinesis-api/.env /path/to/backup/.env
cp -r /path/to/kinesis-api/public/ /path/to/backup/public/
cp -r /path/to/kinesis-api/translations/ /path/to/backup/translations/

Restart the service:

# If using systemd
sudo systemctl start kinesis-api

# Or if running directly
cd /path/to/kinesis-api && ./target/release/kinesis-api &

Automated Backup Scripts

Simple Daily Backup Script

Create a file called backup-kinesis-api.sh:

#!/bin/bash
# Kinesis API Backup Script

# Configuration
KINESIS_DIR="/path/to/kinesis-api"
BACKUP_DIR="/path/to/backups"
BACKUP_NAME="kinesis-api-backup-$(date +%Y%m%d-%H%M%S)"

# Create backup directory
mkdir -p "$BACKUP_DIR/$BACKUP_NAME"

# Optional: Stop the container for consistent backups
docker stop kinesis-api

# Copy the data
cp -r "$KINESIS_DIR/data" "$BACKUP_DIR/$BACKUP_NAME/"
cp "$KINESIS_DIR/.env" "$BACKUP_DIR/$BACKUP_NAME/"
cp -r "$KINESIS_DIR/public" "$BACKUP_DIR/$BACKUP_NAME/"
cp -r "$KINESIS_DIR/translations" "$BACKUP_DIR/$BACKUP_NAME/"

# Restart the container
docker start kinesis-api

# Compress the backup
cd "$BACKUP_DIR"
tar -czf "$BACKUP_NAME.tar.gz" "$BACKUP_NAME"
rm -rf "$BACKUP_NAME"

# Optional: Rotate backups (keep last 7 days)
find "$BACKUP_DIR" -name "kinesis-api-backup-*.tar.gz" -type f -mtime +7 -delete

echo "Backup completed: $BACKUP_DIR/$BACKUP_NAME.tar.gz"

Make the script executable and schedule it with cron:

chmod +x backup-kinesis-api.sh
crontab -e

Add a line to run it daily at 2 AM:

0 2 * * * /path/to/backup-kinesis-api.sh

Restoring from Backup

Kinesis API provides multiple restoration methods depending on how your backup was created:

1. Built-in System Restoration (Recommended)

The built-in backup system provides the simplest restoration process:

Through Web Interface:

Access the Backups Page: Log in as a ROOT user and navigate to /web/backups
Select Backup: Find the backup you want to restore from the list
Click Restore: Click the restore button (refresh icon) next to your chosen backup
Confirm Action: Confirm the restoration in the warning dialog
Automatic Process: The system will:
- Replace all current data with backup data
- Restart the database engine automatically
- Verify the restoration was successful

Through API:

# Replace with your actual values
curl -X GET "http://your-api-url/backup/restore?uid=1&id=backup_id" \
  -H "Authorization: Bearer your-jwt-token"

Important Notes:

⚠️ Warning: Restoring a backup will replace ALL current data with the backup data
This action cannot be undone
The system automatically handles database engine restart
No manual file manipulation is required

Choosing the Right Backup:

When selecting a backup for restoration:

Check Creation Time: Ensure you're selecting the backup from the correct time period
Read Description: Use backup descriptions to identify the purpose (e.g., "Before major update")
Consider Data Loss: Any data created after the backup timestamp will be lost
Verify Backup Age: Check that the backup hasn't expired and been automatically cleaned up

2. Manual File-Based Restoration

For backups created using manual file methods:

Docker Installation Restoration:

Stop the running instance:
```
docker stop kinesis-api
```

Replace the data with the backup:

# If your backup is compressed
tar -xzf kinesis-backup.tar.gz

# Replace the current data
rm -rf data/ .env public/ translations/
cp -r backup/data/ .
cp backup/.env .
cp -r backup/public/ .
cp -r backup/translations/ .

Restart the service:
```
docker start kinesis-api
```

Native Installation Restoration:

Stop the Kinesis API service:

# If using systemd
sudo systemctl stop kinesis-api

# Or if running directly
kill $(pgrep kinesis-api)

Replace the files:

# Backup current state (optional safety measure)
cp -r /path/to/kinesis-api/data/ /path/to/kinesis-api/data.backup/

# Restore from backup
rm -rf /path/to/kinesis-api/data/
cp -r /path/to/backup/data/ /path/to/kinesis-api/
cp /path/to/backup/.env /path/to/kinesis-api/
cp -r /path/to/backup/public/ /path/to/kinesis-api/
cp -r /path/to/backup/translations/ /path/to/kinesis-api/

Restart the service:

# If using systemd
sudo systemctl start kinesis-api

# Or if running directly
cd /path/to/kinesis-api && ./target/release/kinesis-api &

3. Hybrid Restoration Approach

You can also combine methods for maximum flexibility:

Scenario: Restore Built-in Backup to External Environment

Download Backup: Use the built-in system to create a backup
Export Data: Access the backup files from the system
Manual Transfer: Copy to your target environment
Manual Restoration: Use file-based restoration on the target

Scenario: Import Manual Backup into Built-in System

Create Manual Backup: Using your existing file-based process
Import to System: Manually copy files to Kinesis API directory
Create Built-in Backup: Use the web interface to create a new backup for future use
Built-in Restoration: Use the integrated system for future restorations

Restoration Best Practices

Before Restoration:

Create Current Backup: Always backup your current state before restoring
Verify Backup Integrity: Ensure the backup you're restoring from is not corrupted
Check Dependencies: Verify that environment configurations match
Plan Downtime: Coordinate restoration during maintenance windows

During Restoration:

Follow Exact Steps: Don't skip steps or modify the process
Monitor Logs: Watch for error messages during the restoration
Verify Completeness: Ensure all files are restored properly

After Restoration:

Test Functionality: Verify that all features work as expected
Check Data Integrity: Confirm that data is accessible and correct
Update Documentation: Record the restoration in your maintenance logs
User Communication: Notify users of any changes or data loss

Troubleshooting Restoration Issues:

Built-in System Issues:

Backup Not Found: Check that the backup hasn't expired
Permission Errors: Ensure you're logged in as a ROOT user
Restoration Fails: Check system logs for specific error messages

Manual Restoration Issues:

File Permission Errors: Ensure proper ownership and permissions
Database Corruption: Try using an earlier backup
Configuration Mismatches: Verify environment variables match

Recovery from Failed Restoration:

If a restoration fails:

Stop the Service: Prevent further damage
Restore Previous State: Use your pre-restoration backup
Investigate Cause: Check logs and file integrity
Try Alternative Method: Consider using the other restoration approach
Seek Support: Contact support if issues persist

Restoration Testing

Regular Testing Schedule:

Test restoration procedures monthly in a non-production environment
Document the complete process and timing
Verify that all data types and features work correctly after restoration

Testing Environment Setup:

Isolated Environment: Use a separate test environment
Production-like Configuration: Mirror your production setup
Test Data: Use anonymized production data for realistic testing

Keyboard shortcuts

Kinesis API Docs