Repository Backup & Restore

OctoMesh provides comprehensive backup and restore capabilities for repositories through the octo-cli tool. These operations are executed by the bot service and ensure data integrity and availability for disaster recovery scenarios.

Repository Backup

Repository backups create compressed archives containing all tenant data, including entities, associations, and metadata. Backups are performed using the dump command.

Backup Command Syntax

octo-cli -c dump -tid <tenant-id> -f <output-file>

Parameters

Parameter	Description	Example
`-c dump`	Command to create backup	Required
`-tid <id>`	Tenant ID to backup	`sbeg`, `energy-community`
`-f <file>`	Output file path (tar.gz format)	`./backup.tar.gz`, `/path/to/backup.tar.gz`

Backup Example

# Create backup of 'sbeg' tenant
octo-cli -c dump -tid sbeg -f ./sbeg-backup-2025-08-12.tar.gz

Backup Content

The backup archive contains:

All runtime entities and their attributes
Association data linking entities
Construction kit metadata
AutoIncrement states
Tenant configuration and settings
Index definitions and constraints

Repository Restore

Repository restoration recreates tenant data from backup archives. The restore process handles both new tenant creation and existing tenant replacement scenarios.

Restore Command Syntax

octo-cli -c restore -tid <tenant-id> -db <database-name> -f <backup-file> -w

Parameters

Parameter	Description	Example
`-c restore`	Command to restore backup	Required
`-tid <id>`	Target tenant ID	`sbeg`, `energy-community`
`-db <name>`	Target database name	`sbeg`, `production-db`
`-f <file>`	Backup file path (tar.gz format)	`/path/to/backup.tar.gz`
`-w`	Watch mode for progress monitoring	Optional but recommended

Restore Example

# Restore 'sbeg' tenant from backup file
octo-cli -c restore -tid sbeg -db sbeg -f /users/gerald/Downloads/mongodb-backup-sbeg-2025_08_12_03_00.tar.gz -w

Restore Behavior

The restore operation follows specific rules based on the target tenant's existence:

Existing Tenant

Complete Replacement: If the tenant already exists, it is completely replaced with backup data
Data Overwrite: All existing entities, associations, and configurations are removed
Downtime: The tenant is temporarily unavailable during the replacement process

New Tenant

Fresh Creation: Creates a new tenant with the specified tenant ID
Database Attachment: Attaches the tenant to the specified database
Configuration Setup: Establishes all necessary indexes and constraints

Backup & Restore Workflow

Regular Backup Strategy

#!/bin/bash
# Daily backup script example

DATE=$(date +%Y_%m_%d_%H_%M)
TENANT_ID="sbeg"
BACKUP_DIR="/backups"
BACKUP_FILE="${BACKUP_DIR}/mongodb-backup-${TENANT_ID}-${DATE}.tar.gz"

# Create backup
octo-cli -c dump -tid ${TENANT_ID} -f ${BACKUP_FILE}

# Verify backup was created
if [ -f "${BACKUP_FILE}" ]; then
    echo "Backup created successfully: ${BACKUP_FILE}"
    # Optional: Upload to cloud storage, notify administrators, etc.
else
    echo "ERROR: Backup failed for tenant ${TENANT_ID}"
    exit 1
fi

Disaster Recovery Process

# 1. Stop application services (if needed)
# systemctl stop octo-mesh-service

# 2. Restore from latest backup
octo-cli -c restore -tid production -db production-db -f /backups/latest-backup.tar.gz -w

# 3. Verify restoration
# Check entity counts, run validation queries, etc.

# 4. Restart services
# systemctl start octo-mesh-service

Best Practices

Backup Strategy

Regular Schedule: Implement automated daily or hourly backups based on data criticality
Retention Policy: Keep multiple backup versions (daily for 30 days, weekly for 12 weeks, monthly for 12 months)
Offsite Storage: Store backups in multiple locations (local, cloud, remote datacenter)
Validation: Periodically test backup integrity by performing test restores

Backup Naming

Consistent Format: Use standardized naming with timestamps: mongodb-backup-{tenant}-{YYYY_MM_DD_HH_MM}.tar.gz
Descriptive Names: Include tenant ID and environment information
Version Control: Maintain backup catalogs with metadata about each backup

Restore Planning

Test Environment: Always test restore procedures in non-production environments first
Downtime Planning: Schedule restore operations during maintenance windows
Verification Steps: Prepare validation queries to confirm restore success
Rollback Plan: Maintain current backup before performing restore operations

Security Considerations

Access Control: Restrict backup and restore operations to authorized personnel only
Encryption: Encrypt backup files at rest and in transit
Audit Trail: Log all backup and restore operations for compliance
Network Security: Use secure channels for backup file transfers

Monitoring & Verification

Backup Verification

# Check backup file size and integrity
ls -lh ./backup.tar.gz
tar -tzf ./backup.tar.gz | head -10

# Verify backup contains expected collections
# (Restore to test environment and validate)

Restore Verification

# After restore, verify tenant is accessible
octo-cli -c query -tid sbeg -q "{ \"ckTypeId\": \"System/Entity\" }" -l 5

# Check entity counts match expectations
# Verify critical business data is present
# Test application functionality

warning

Critical Safety Notice: Restore operations completely replace existing tenant data. Always create a current backup before performing restore operations in production environments.

tip

Use the -w (watch) flag during restore operations to monitor progress and identify potential issues early in the process.

Troubleshooting

Common Issues

Insufficient Disk Space: Ensure adequate space for backup files and extraction
Permission Errors: Verify file system permissions for backup directories
Network Timeouts: For large backups, ensure stable network connections
Version Compatibility: Ensure backup compatibility with current OctoMesh version

Recovery Scenarios

Partial Data Loss: Use selective restore with specific date ranges
Corruption Recovery: Restore from the most recent clean backup
Migration Support: Use backup/restore for tenant migration between environments