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

By default a backup contains the tenant's MongoDB repository data (entities, associations, and metadata) as a compressed *.tar.gz. With the --include-archive-data option the backup additionally captures the tenant's CrateDB stream-data archives, producing a larger *.octobak.zip container. Backups are performed using the dump command.

Backup Command Syntax

octo-cli -c dump -tid <tenant-id> -f <output-file> [--include-archive-data]

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. Use `.tar.gz` for a MongoDB-only backup, or `.octobak.zip` when including archive data	`./backup.tar.gz`, `./backup.octobak.zip`
`-iad`, `--include-archive-data`	Also include the tenant's CrateDB stream-data archives (produces an `*.octobak.zip`). Requires stream data enabled on the tenant	Optional

Backup Example

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

# Backup including CrateDB stream-data archives (produces an .octobak.zip)
octo-cli -c dump -tid sbeg -f ./sbeg-backup-2025-08-12.octobak.zip --include-archive-data

Backup Content

A plain *.tar.gz backup contains the MongoDB repository data:

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

When --include-archive-data is used, the artifact is an *.octobak.zip that wraps the MongoDB dump plus the tenant's CrateDB stream-data archives (one NDJSON file per archive) and a manifest describing each archive's schema and row count.

tip

To export or import the rows of a single archive (rather than a whole tenant), use the dedicated ExportArchiveData and ImportArchiveData commands. See the Stream Data archives guide for the archive concepts.

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 [--restore-archive-data]

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`
`-oldDb <name>`	When the database had a different name before, you can use this option to be able to restore it to a "new" tenant name	`sbeg`, `production-db`
`-f <file>`	Backup file path. Accepts a `.tar.gz` (MongoDB-only) or an `.octobak.zip` (MongoDB + archive data)	`/path/to/backup.octobak.zip`
`-rad`, `--restore-archive-data`	Also restore the CrateDB stream-data archives from an `.octobak.zip`. No-op on a plain `.tar.gz`	Optional
`-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
Secret Attributes: Backups contain Secret attributes in encrypted form. A restore keeps them encrypted. Into another environment, values with an unknown key id read as not set (keyMissing) and must be re-entered, or become readable when the source key is added to the key ring. Disaster recovery needs the dump and the key ring backup (see Restore across environments)

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