Backups and Recovery

Backups protect your Legend instance against data loss, corruption, or accidental deletion. Legend provides automated daily backups and allows you to create manual backups on demand. This guide explains what is included in backups, how to configure backup settings, and how to restore from backup when needed.

Accessing Backup Management

To access backup management:

1. Click your user menu in the top-right corner
2. Select Admin Panel from the dropdown
3. Click Backups in the admin sidebar

Only users in the Admins group can access backup management.

What Is Included in Backups

Legend backups include the SQLite database, which contains:

• User accounts: All user profiles, authentication credentials, and account settings
• Groups: Group definitions and user memberships
• Configuration: System settings, OIDC configuration, and branding settings
• Audit logs: Complete audit log history (subject to retention policies)
• License information: License keys, tier information, and usage data
• Categories and tags: Category definitions, tag definitions, and color assignments
• Alert configurations: Alert banner definitions and schedules

What Is NOT Included in Backups

Legend backups do not include:

• Catalog YAML files: Entity definitions (landmarks, people, teams) stored in the data directory
• Documentation files: Markdown documentation attached to entities
• Branding assets: Custom logos and favicons stored in the data directory
• Link health data: Link health scan results and history

These files are stored separately from the SQLite database and must be backed up independently. See Offsite Backup Recommendations for guidance on backing up the complete data directory.

Incomplete Backups

If you rely solely on Legend’s built-in backups, you will lose entity data, documentation, and branding assets in a disaster scenario. Always back up the complete data directory for comprehensive protection.

Automatic Backups

When automatic backups are enabled, Legend creates a database backup every day at 2:00 AM local time. Automatic backups are enabled by default and require no configuration.

Automatic backup behavior:

• Backups are created at 2:00 AM local time
• Each backup is a complete snapshot of the SQLite database
• Backups are stored in the data directory under backups/
• Backup files are named with timestamps (e.g., legend-2024-01-15-020000.db)
• Automatic backups continue even if the container is restarted

Configuring automatic backups: Automatic backups are controlled by the LEGEND_PUBLIC_ENABLE_BACKUPS environment variable:

• true: Automatic backups are enabled (default)
• false: Automatic backups are disabled

To disable automatic backups, set this environment variable to false and restart the container.

Keep Automatic Backups Enabled

Automatic backups provide a safety net against data loss. Unless you have a comprehensive external backup strategy, keep automatic backups enabled to ensure your data is protected.

Manual Backups

You can create manual backups at any time through the admin panel. Manual backups are useful before making significant changes, testing new features, or creating recovery points for specific events.

To create a manual backup:

1. Navigate to Admin Panel > Backups
2. Click the Create Backup button
3. Legend creates a backup immediately
4. The backup appears in the backup list with a timestamp

Manual backups are stored in the same location as automatic backups and follow the same retention policies.

When to create manual backups:

• Before upgrading Legend to a new version
• Before making significant configuration changes
• Before bulk importing or modifying entities
• Before testing experimental features
• At regular intervals as part of your backup strategy

Backup Retention

Legend automatically manages backup retention to balance storage usage with recovery options:

Retention policy:

• Backups older than 30 days are automatically deleted
• A minimum of 3 backups are always retained, regardless of age
• A maximum of 100 backups are retained at any time

Retention behavior:

• When the maximum number of backups is reached, the oldest backup is deleted
• When a backup exceeds the maximum age, it is deleted (unless it’s one of the 3 most recent)
• Retention is enforced during the backup creation process

Configuring retention: Retention settings are controlled by environment variables:

• LEGEND_BACKUP_MAX_AGE_DAYS: Maximum age in days (default: 30)
• LEGEND_BACKUP_MIN_BACKUPS: Minimum number of backups to retain (default: 3)
• LEGEND_BACKUP_MAX_BACKUPS: Maximum number of backups to retain (default: 100)

Adjust these values based on your storage capacity and recovery requirements.

Storage Considerations

Each backup is a complete copy of the SQLite database. For large instances with extensive audit logs, backup files can be several megabytes in size. Monitor your storage usage and adjust retention settings accordingly.

Viewing Backups

The backup management page displays a list of all available backups:

• Timestamp: When the backup was created
• Size: The size of the backup file
• Type: Whether the backup was automatic or manual
• Actions: Options to download, restore, or delete the backup

Sorting and filtering:

• Backups are sorted by timestamp (newest first)
• Use the filter dropdown to show only automatic or manual backups
• Use the search box to find backups by date or timestamp

Downloading Backups

You can download backup files to your local computer for offsite storage or archival purposes.

To download a backup:

1. Navigate to Admin Panel > Backups
2. Find the backup you want to download
3. Click the Download button next to the backup
4. The backup file is downloaded to your computer

Downloaded backups are standard SQLite database files. You can open them with SQLite tools for inspection or store them for archival purposes.

Backup Security

Backup files contain sensitive data including user credentials and configuration. Store downloaded backups securely and do not share them publicly. Consider encrypting backup files before storing them offsite.

Restoring from Backup

Restoring from backup replaces the current SQLite database with the contents of the backup file. This operation is irreversible and will overwrite all current data.

To restore from backup:

1. Navigate to Admin Panel > Backups
2. Find the backup you want to restore
3. Click the Restore button next to the backup
4. Legend creates a safety backup of the current database before restoring
5. Confirm the restore operation
6. Legend restores the backup and restarts the application
7. All users are logged out and must log in again

What happens during restore:

• A safety backup of the current database is created automatically
• The current database is replaced with the backup contents
• The application restarts to load the restored data
• All active sessions are invalidated
• Users must log in again with their credentials from the backup

Restore Is Destructive

Restoring from backup overwrites all current data including users, groups, configuration, and audit logs. This operation cannot be undone. Ensure you have selected the correct backup and understand the impact before proceeding.

When to restore from backup:

• After accidental data deletion or corruption
• When configuration changes cause problems
• To recover from a failed upgrade
• To revert to a known-good state after testing

After restoring:

• Verify that the restored data is correct
• Check that users can log in successfully
• Review configuration settings to ensure they are correct
• Update any external systems that depend on Legend data

Offsite Backup Recommendations

Legend’s built-in backups protect against database corruption and accidental deletion, but they do not protect against complete system failure, hardware loss, or disasters. For comprehensive protection, implement an offsite backup strategy.

Recommended approach:

1. Enable Legend’s automatic backups for database protection
2. Back up the complete data directory regularly
3. Store backups in a separate location (cloud storage, offsite server, etc.)
4. Test restore procedures periodically

Backing up the data directory: The data directory contains all Legend data including the SQLite database, catalog YAML files, documentation, and branding assets. Back up the entire directory to ensure complete recovery.

Data directory location: The data directory location is controlled by the LEGEND_DATA_DIR environment variable. By default, it is /app/data inside the container, which is typically mounted to a host directory.

Backup methods:

• File system backup: Use your server’s backup tools to back up the data directory
• Cloud storage: Sync the data directory to cloud storage (AWS S3, Google Cloud Storage, etc.)
• Version control: Store catalog YAML files in Git for version history
• External backup service: Use a third-party backup service for automated offsite backups

Backup frequency:

• Database: Daily (handled by Legend’s automatic backups)
• Complete data directory: Daily or weekly, depending on change frequency
• Catalog YAML files: After significant changes (if using version control)

Test Your Backups

Regularly test your backup and restore procedures to ensure they work correctly. A backup is only valuable if you can restore from it successfully. Schedule periodic restore tests as part of your disaster recovery planning.

Backup File Format

Legend backups are standard SQLite database files. You can inspect backup contents using SQLite tools:

Viewing backup contents:

sqlite3 legend-2024-01-15-020000.db
.tables
SELECT * FROM users LIMIT 10;
.quit

Common tables in backup files:

• users: User accounts and credentials
• groups: Group definitions
• user_groups: User-group memberships
• config: System configuration
• audit_logs: Audit log entries
• categories: Category definitions
• tags: Tag definitions

Backup file naming:

• Automatic backups: legend-YYYY-MM-DD-HHMMSS.db
• Manual backups: legend-manual-YYYY-MM-DD-HHMMSS.db

Troubleshooting

Automatic backups not running:

• Verify LEGEND_PUBLIC_ENABLE_BACKUPS is set to true
• Check that the container has write access to the data directory
• Review container logs for backup-related errors
• Ensure sufficient disk space is available

Cannot create manual backup:

• Verify you have administrator privileges
• Check that the data directory has sufficient disk space
• Ensure the container has write access to the backups directory
• Review container logs for error messages

Cannot restore from backup:

• Verify you have administrator privileges
• Check that the backup file is not corrupted
• Ensure sufficient disk space is available for the restore operation
• Review container logs for restore-related errors

Backup files missing:

• Check that the backups directory exists and is accessible
• Verify the container has write access to the backups directory
• Review retention settings to ensure backups are not being deleted prematurely
• Check disk space to ensure backups are not being deleted due to space constraints

Restore failed:

• Check that the backup file is valid and not corrupted
• Ensure sufficient disk space is available
• Review container logs for detailed error messages
• Try restoring from a different backup file
• Contact Legend support if the issue persists

Best Practices

Backup Strategy:

• Enable automatic backups for database protection
• Create manual backups before significant changes
• Back up the complete data directory for comprehensive protection
• Store backups offsite to protect against system failure

Retention Management:

• Adjust retention settings based on your storage capacity
• Keep at least 7-14 days of backups for recovery options
• Monitor backup storage usage and adjust as needed
• Delete old backups that are no longer needed

Security:

• Store backup files securely and restrict access
• Encrypt backup files before storing them offsite
• Do not share backup files publicly or commit them to version control
• Rotate backup encryption keys periodically

Testing:

• Test restore procedures regularly to ensure they work
• Perform restore tests in a staging environment before production
• Document your restore procedures for disaster recovery
• Train administrators on backup and restore procedures

Next Steps

After configuring backups, proceed to Alert Banners to configure system-wide notifications, or Link Health Monitoring to monitor entity link availability.