Skip to main content

Backup and Restore

This guide covers how to create backups of your FOVEA data and restore them when needed. For detailed information about export and import options, see Exporting Data and Importing Data.

Why Backup?​

Regular backups protect your work from:

  • Accidental deletion of personas, annotations, or ontologies
  • System failures or data corruption
  • Moving to a new FOVEA instance
  • Sharing work with collaborators

What Gets Backed Up?​

A full FOVEA backup includes:

Data TypeDescription
PersonasYour analyst personas with roles and information needs
OntologiesEntity types, event types, role types, and relation types
World StateEntities, events, times, locations, and collections
SummariesVideo summaries created by personas
ClaimsClaims extracted from summaries
Claim RelationsRelationships between claims
AnnotationsBounding box sequences linking objects to video frames

Quick Backup​

Using the UI​

  1. Click the Export button in the toolbar
  2. Select Export All to include all data types
  3. Keep Keyframes Only selected (smaller file size)
  4. Click Export
  5. Save the downloaded .jsonl file to a safe location

Using the API​

curl "http://localhost:3001/api/export/all" \
  -H "Cookie: session_token=YOUR_TOKEN" \
  --output backup-$(date +%Y%m%d).jsonl

Backup File Naming​

Use a consistent naming convention:

fovea-backup-YYYY-MM-DD.jsonl
fovea-backup-2025-01-15.jsonl

For multiple backups per day:

fovea-backup-2025-01-15-morning.jsonl
fovea-backup-2025-01-15-afternoon.jsonl

Restore from Backup​

Using the UI​

  1. Click the Import button in the toolbar
  2. Drag and drop your backup file or click to browse
  3. Review the import preview
  4. Configure conflict resolution (usually Skip existing for restore)
  5. Click Import
  6. Wait for the import to complete

Using the API​

curl -X POST "http://localhost:3001/api/import" \
  -H "Cookie: session_token=YOUR_TOKEN" \
  -F "file=@backup-2025-01-15.jsonl"

Backup Strategies​

Daily Backups​

For active projects, create daily backups:

#!/bin/bash
# Run daily via cron
BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y%m%d)
curl "http://localhost:3001/api/export/all" \
  -H "Cookie: session_token=YOUR_TOKEN" \
  --output "$BACKUP_DIR/fovea-backup-$DATE.jsonl"

# Keep last 30 days
find "$BACKUP_DIR" -name "fovea-backup-*.jsonl" -mtime +30 -delete

Before Major Changes​

Always backup before:

  • Deleting personas or ontologies
  • Bulk editing annotations
  • Upgrading FOVEA
  • Running experimental analysis

Project Milestones​

Create named backups at project milestones:

fovea-backup-phase1-complete.jsonl
fovea-backup-review-ready.jsonl
fovea-backup-final.jsonl

Partial Restore​

You don't have to restore everything. Use selective import:

Restore Only Personas​

curl "http://localhost:3001/api/export/personas" \
  --output personas-backup.jsonl

# Later, import just personas
curl -X POST "http://localhost:3001/api/import" \
  -F "file=@personas-backup.jsonl"

Restore Only Summaries​

curl "http://localhost:3001/api/export/summaries" \
  --output summaries-backup.jsonl

# Later, import just summaries
curl -X POST "http://localhost:3001/api/import" \
  -F "file=@summaries-backup.jsonl"

Conflict Resolution During Restore​

When restoring to a system with existing data:

SituationRecommended Resolution
Restoring to empty systemSkip existing (nothing will conflict)
Merging with existing dataSkip existing (keep current, add new)
Overwriting old dataReplace existing (backup overwrites current)
Keeping both versionsRename (creates copies with new IDs)

Restore to Different Environment​

To move data between FOVEA instances:

  1. Export from source instance
  2. Transfer the .jsonl file to the target machine
  3. Import to target instance
Video References

Annotations reference videos by ID. If videos don't exist in the target system, annotations linking to those videos will be skipped during import.

Verifying Backups​

After creating a backup, verify it's valid:

Check File Size​

ls -lh backup.jsonl
# Should be > 0 bytes

Count Lines​

wc -l backup.jsonl
# Should match expected number of items

Validate JSON​

# Each line should be valid JSON
while read line; do
  echo "$line" | jq . > /dev/null || echo "Invalid line"
done < backup.jsonl

Test Restore​

Periodically test restoring to a test instance:

  1. Set up a test FOVEA instance
  2. Import the backup
  3. Verify data appears correctly
  4. Delete test instance

Troubleshooting​

Import Failed with Errors​

Check the import result for specific errors:

{
  "success": false,
  "errors": [
    {"line": 42, "message": "Video xyz-123 not found"}
  ]
}

Common causes:

  • Missing videos (annotations reference non-existent videos)
  • Invalid JSON (corrupted backup file)
  • Schema mismatch (backup from incompatible version)

Missing Data After Restore​

Check import warnings:

{
  "warnings": [
    {"line": 15, "message": "Skipped duplicate persona"}
  ]
}

If items were skipped due to conflicts, try:

  • Using Replace existing instead of Skip existing
  • Clearing existing data before import

Large Backup Files​

If backups are too large:

  1. Use Keyframes Only mode (not fully interpolated)
  2. Export only the data types you need
  3. Filter by specific personas or videos
  4. Split into multiple smaller exports

Best Practices​

  1. Regular backups: Daily for active projects, weekly for archived projects
  2. Test restores: Periodically verify backups can be restored
  3. Multiple locations: Keep copies in different locations (local + cloud)
  4. Version control: Store backups in git for text-based change tracking
  5. Document: Note what each backup contains and when it was created
  6. Retention policy: Define how long to keep old backups