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
• Selective Git restore - Pull individual categories back from any backup commit

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 (must be private — see warning above)
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 (must be private — see warning above)
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 (must be private — see warning above)
2. Generate a Personal Access Token (PAT):
   • Go to Settings → Applications
   • Under Manage Access Tokens, expand Generate New Token
   • Enter a name for the token
   • Under Repository and organization access, choose All (public, private, and limited)
   • Under Repository permissions, set repository to Read and write
   • 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 your instance is served under a URL path (a ROOT_URL subpath such as https://example.com/gitea), include that prefix in the URL — e.g. https://example.com/gitea/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 (must be private — see warning above)
2. Generate a Personal Access Token (PAT):
   • Go to Settings → Applications
   • Click New access token
   • Enter a name for the token
   • Under Repository and organization access, choose either:
     • All to allow access to all repositories
     • Specific and select your Bambuddy backup repository
   • Under Repository permissions, set repository to Read and write (the write:repository scope)
   • 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 your instance is served under a URL path (a ROOT_URL subpath such as https://example.com/forgejo), include that prefix in the URL — e.g. https://example.com/forgejo/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/
│   ├── bambu/
│   │   └── {account}/          # "global", or "user-{id}" when auth is on
│   │       ├── filament.json
│   │       ├── printer.json
│   │       └── process.json
│   └── orca/
│       └── {account}/
│           ├── filament.json
│           ├── printer.json
│           └── process.json
├── settings/
│   └── app_settings.json
├── spools/
│   ├── inventory.json
│   └── usage_history.json
└── archives/
    └── print_history.json

What cloud profiles contain¶

Only your custom presets. Bambu Cloud's bundled catalogue is skipped: it is the same hundreds of entries for every user, always re-downloadable, and cannot be recreated under your account anyway — including it would rewrite the repository on every run for nothing.

Each Bambu preset is stored with the payload needed to recreate it, not just its name. Orca profiles keep their full content, which the Orca sync API returns inline.

If an account's cloud session has expired, that account is skipped and the run says so in the log — the backup never signs anyone out on its own. For Orca Cloud the stored credentials are cleared the next time you open Orca Cloud Profiles, where you can pair again.

backup_metadata.json reports what was actually collected, per cloud and per account. If the category is enabled but nothing came back, it records false and the reason appears in the application log as a warning.

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)

Restoring from a Git Backup¶

Every backup commit is a restore point. The Restore from Git button on the Git Backup card lets you pick one of those commits and pull selected categories back into Bambuddy — without touching anything you didn't select.

How to Restore¶

1. Go to Settings > Backup & Restore
2. On the Git Backup card, click Restore from Git
3. Pick a Backup commit from the dropdown (the 20 most recent, newest first)
4. Tick the categories you want under What to restore
5. Choose whether to Overwrite existing entries (see below)
6. Click Restore

The modal shows how many items each category holds in the commit you picked, and greys out any category that commit doesn't contain — a category you only enabled recently simply isn't in older commits. That number is what the result summary adds up to afterwards: restored plus skipped plus failed always equals it. Spool inventory counts the usage records alongside the spools, since both are restored under that category.

What Can Be Restored¶

Overwrite vs. Skip¶

The Overwrite existing entries toggle decides what happens when something in the backup already exists locally:

Leave it off to recover something you deleted by accident. Turn it on to roll your current data back to how it looked at that commit. K-profiles are the one category the toggle doesn't reach — see the note below.

After Restoring¶

The result summary lists restored / skipped / failed counts per category, plus any notes explaining a skip. Those three add up to the item count the preview showed for that category.

If App settings was one of the restored categories, Bambuddy reloads the page when you close the modal. Most restored settings appear immediately, but the ones the interface applies at startup — the display language and whether authentication is on — won't until it reloads.

If any MQTT settings were restored, Bambuddy reconnects the MQTT relay to the restored broker immediately, so you don't need to restart for those to take effect. The MQTT password isn't in the backup, so a broker that needs a different one won't connect until you re-enter it — the result summary says when the relay couldn't reconnect.

Restores are recorded in Backup History with a restore trigger, alongside your backup runs.

Restore API Endpoints¶

POST /github-backup/restore takes ref (a commit SHA, or HEAD for the branch tip), categories (one or more of kprofiles, settings, spools, archives), and overwrite_existing:

{
  "ref": "debe2cb",
  "categories": ["spools", "settings"],
  "overwrite_existing": false
}

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.

sudo systemctl edit bambuddy

[Service]
ReadWritePaths=/mnt/nasbackup

sudo systemctl restart bambuddy

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¶