Backup & Restore¶

Protect your print history with database backups and restore when needed.

Overview¶

Bambuddy's backup system:

• Full database backup - All your data in one file
• User settings included - Preferences preserved
• Archives included - Print history saved
• ZIP format - Includes 3MF files and thumbnails when selected
• Git backup - Automatic cloud backup of profiles and settings to a Git provider

Git Profile Backup¶

Automatically back up your K-profiles, cloud profiles, app settings, spool inventory, and print archive history to a Git repository.

Bambuddy supports multiple Git providers. Choose one below and follow the setup steps.

Setup¶

GitHub¶

1. Create a GitHub repository (can be private)
2. Generate a Personal Access Token (PAT):
   • Go to GitHub Personal Access Tokens (https://github.com/settings/tokens)
   • Click Generate new token, then Generate new token (classic)
   • Choose your expiration timeframe (No expiration is recommended)
   • Under Select scopes, check repo (required for repository access and commits)
3. Configure in Bambuddy:
   • Go to Settings → Backup & Restore
   • Enter your repository URL (e.g., https://github.com/username/bambuddy-backup)
   • Enter your PAT (from Step 2)
   • Click Test Connection to verify

GitLab¶

1. Create a GitLab repository (can be private)
2. Generate a Personal Access Token (PAT):
   • Go to GitLab Personal Access Tokens (https://gitlab.com/-/user_settings/personal_access_tokens)
   • Under Personal access tokens, click Generate token, then Legacy token
   • Under scopes, check the api scope (required for repository access and commits)
3. Configure in Bambuddy:
   • Go to Settings → Backup & Restore
   • Select GitLab from the provider dropdown
   • Enter your repository URL (e.g., https://gitlab.com/username/bambuddy-backup)
   • If you are hosting locally without HTTPS, be sure to check the Allow insecure HTTP checkbox
   • Enter your PAT (from Step 2)
   • Click Test Connection to verify

Gitea¶

1. Create a new repository (can be private)
2. Generate a Personal Access Token (PAT):
   • Go to Settings → Applications
   • Under Access Tokens, enter a name for this token and choose All (public, private, and limited)
   • Select Read and write under the repository permissions
   • Click Generate token
3. Configure in Bambuddy:
   • Go to Settings → Backup & Restore
   • Select Gitea from the provider dropdown
   • Enter your repository URL (e.g., https://example.com/username/bambuddy-backup)
   • If you are hosting locally without HTTPS, be sure to check the Allow insecure HTTP checkbox
   • Enter your PAT (from Step 2)
   • Be sure to specify the right Branch (main/master/etc)
   • Click Test Connection to verify

Forgejo¶

1. Create a new repository (can be private)
2. Generate a Personal Access Token (PAT):
   • Go to Settings → Applications
   • Under Manage Access Tokens, enter a name for this token and click Generate Token
3. Configure in Bambuddy:
   • Go to Settings → Backup & Restore
   • Select Forgejo from the provider dropdown
   • Enter your repository URL (e.g., https://example.com/username/bambuddy-backup)
   • If you are hosting locally without HTTPS, be sure to check the Allow insecure HTTP checkbox
   • Enter your PAT (from Step 2)
   • Click Test Connection to verify

What's Backed Up¶

Schedule Options¶

Manual Backup¶

Click Backup Now to trigger an immediate backup.

Repository Structure¶

repo/
├── backup_metadata.json
├── kprofiles/
│   └── {serial_number}/
│       ├── 0.2.json
│       ├── 0.4.json
│       └── ...
├── cloud_profiles/
│   ├── filament.json
│   ├── printer.json
│   └── process.json
├── settings/
│   └── app_settings.json
├── spools/
│   ├── inventory.json
│   └── usage_history.json
└── archives/
    └── print_history.json

Backup History¶

View backup history in the Backup History section:

• Status (success, failed, skipped)
• Trigger (manual or scheduled)
• Files changed
• Commit SHA (linked to GitHub)

Scheduled Local Backups¶

Automate local backups on a recurring schedule so you never forget to protect your data.

Overview¶

The Scheduled Backups card in Settings > Backup lets you configure automatic local backups that run in the background. Each backup produces the same complete ZIP file as a manual backup (database + all data directories), stored on disk where you can easily copy them to a NAS or external drive.

Works with both SQLite and PostgreSQL installations.

Configuration¶

Managing Backups¶

Each backup in the list supports three actions:

• Download -- download the ZIP file to your browser
• Restore -- restore directly from the backup (same as manual restore)
• Delete -- remove the backup file from disk

Click Run Now to trigger an immediate backup outside the schedule.

Docker Setup¶

Docker users should mount the backup output directory as a volume so backups are persisted outside the container. Add a bind mount to your docker-compose.yml:

services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    container_name: bambuddy
    network_mode: host
    volumes:
      - bambuddy_data:/app/data
      - bambuddy_logs:/app/logs
      - /path/to/nas/bambuddy-backups:/app/data/backups  # Scheduled backup output
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

volumes:
  bambuddy_data:
  bambuddy_logs:

Or with docker run:

docker run -d \
  --network host \
  -v bambuddy_data:/app/data \
  -v bambuddy_logs:/app/logs \
  -v /path/to/nas/bambuddy-backups:/app/data/backups \
  -e TZ=Europe/Berlin \
  --name bambuddy \
  --restart unless-stopped \
  ghcr.io/maziggy/bambuddy:latest

Non-Docker Setup¶

For bare-metal or virtual machine installs, set the Output path in the UI to any directory your Bambuddy process can write to -- a local folder, a mounted network drive, or an external USB drive.

API Endpoints¶

For automation or monitoring, the scheduled backup system exposes a REST API:

Creating a Local Backup¶

Manual Backup¶

1. Go to Settings > Backup & Restore
2. Click Download Backup
3. Wait for backup to complete (progress indicator shown)
4. ZIP file downloads automatically

Backup Contents¶

The backup is a complete ZIP file containing:

Backup File¶

Format¶

Backup files are ZIP archives:

bambuddy-backup-20260201-143022.zip

ZIP Structure¶

bambuddy-backup-YYYYMMDD-HHMMSS.zip
├── bambuddy.db              # Database (portable SQLite format, works on both SQLite and PostgreSQL installs)
├── archive/                 # All archive data
│   ├── <archive_id>/        # Individual archive folders
│   │   ├── *.3mf            # Archived print files
│   │   ├── thumbnail.png    # Thumbnails
│   │   ├── timelapse.mp4    # Timelapses
│   │   ├── source.3mf       # Original source 3MF
│   │   ├── *.f3d            # Fusion 360 files
│   │   └── photos/*.jpg     # Photo attachments
│   └── library/             # File Manager
│       ├── files/           # Uploaded files
│       └── thumbnails/      # Generated thumbnails
├── virtual_printer/         # Pending uploads
├── projects/                # Project files
├── icons/                   # Custom printer icons
└── plate_calibration/       # Plate detection references

File Size¶

Typical sizes depend on your archive content:

• Small archive (100 prints, no timelapses): ~100-500 MB
• Medium archive (500 prints, some timelapses): ~1-5 GB
• Large archive (1000+ prints, full timelapses): ~10+ GB

Restoring from Backup¶

Full Restore¶

Restore everything from a backup ZIP:

1. Go to Settings > Backup & Restore
2. Click Restore Backup
3. Select your backup ZIP file
4. Wait for restore to complete (progress indicator shown)
5. Restart Bambuddy when prompted

Portable Backups¶

Backups are fully portable between installations:

• Different servers: Move from one machine to another
• Different paths: Works even if data directory changed
• Different Docker volumes: Migrate between container setups
• Different database backends: Restore a SQLite backup into a PostgreSQL install (and vice versa)

The backup system always exports data in portable SQLite format, regardless of which database backend you use. When restoring into PostgreSQL, Bambuddy automatically converts data types (booleans, datetimes) and handles foreign key constraints.

Manual Database Access¶

/path/to/bambuddy/bambuddy.db

cp bambuddy.db bambuddy_backup_$(date +%Y%m%d).db

psql "postgresql://user:pass@host:5432/bambuddy"

pg_dump -Fc "postgresql://user:pass@host:5432/bambuddy" > bambuddy_backup_$(date +%Y%m%d).dump

pg_restore --clean --if-exists -d "postgresql://user:pass@host:5432/bambuddy" bambuddy_backup.dump

Restore from SQL¶

sqlite3 new.db < backup.sql ```

Downloading Archives¶

3MF files aren't in database backups. Download separately:

Individual Download¶

1. Open an archive
2. Click Download 3MF

Bulk Export¶

1. Go to Archives
2. Click Export
3. Select Include 3MF files
4. Download the archive

Recovery Scenarios¶

Lost Database¶

If database is corrupted or deleted:

1. Stop Bambuddy
2. Remove corrupted bambuddy.db
3. Start Bambuddy (creates fresh database)
4. Go to Settings > Backup
5. Restore from your backup

New Installation¶

Moving to a new server:

1. Install Bambuddy on new server
2. Copy backup file to new server
3. Go to Settings > Backup
4. Full restore from backup

Data Migration¶

Moving between versions:

1. Create backup on old version
2. Upgrade Bambuddy
3. If needed, restore from backup

Best Practices¶

Recommended Backup Frequency¶

Storage¶

• Keep backups off the Bambuddy server
• Use cloud storage (Dropbox, Google Drive, etc.)
• Keep multiple versions

Testing¶

• Periodically test restoring
• Verify backup integrity
• Document your backup process

Tips¶