Skip to content

Backup and Restore

Jump to bottom
Ken Lasko edited this page Apr 3, 2026 · 3 revisions

Backup and Restore

Monize includes a full backup and restore system to protect your financial data. You can create manual backups on demand, schedule automatic backups with intelligent retention policies, and restore from any backup file.

Table of Contents

Manual Backup

You can download a full backup of your data at any time from the Settings page.

  1. Navigate to Settings (gear icon in the top-right corner)
  2. Scroll to the Backup & Restore section
  3. Click Export Backup
  4. Your browser will download a file named monize-backup-YYYY-MM-DD.json.gz

Backup & Restore

The backup is a gzip-compressed JSON file containing all of your financial data. It is streamed from the server to avoid memory issues with large datasets.

Restoring from a Backup

Restoring replaces all of your existing data with the contents of the backup file. This is useful for recovering from data loss, migrating to a new server, or reverting after an unwanted change.

Caution: Restoring a backup permanently replaces all of your current data. This operation cannot be undone. Consider exporting a backup of your current data first.

How to Restore

  1. Navigate to Settings (gear icon in the top-right corner)
  2. Scroll to the Backup & Restore section
  3. Click Restore Backup
  4. Select a backup file (.json, .json.gz, or .gz)
  5. Enter your password to confirm (or re-authenticate via SSO if using OIDC)
  6. Click Confirm Restore

After a successful restore, a summary is displayed showing the number of records restored for each data type.

Restore Summary

How Restore Works

The restore process runs inside a database transaction with three phases:

  1. Delete -- All existing user data is removed in foreign-key-safe order
  2. Insert -- Backup data is inserted in dependency order to satisfy foreign key relationships
  3. Link -- Deferred relationships (parent categories, linked accounts, linked transactions, etc.) are reconnected

If any step fails, the entire operation is rolled back and no data is changed.

Automatic Backups

Monize can automatically back up your data on a schedule, saving compressed backup files to a folder on the server.

Enabling Auto-Backup

  1. Navigate to Settings (gear icon in the top-right corner)
  2. Scroll to the Automatic Backup section
  3. Toggle Enable Automatic Backups to on
  4. Configure the folder path, frequency, timing, and retention settings
  5. Click Save Settings

Automatic Backup Settings

Folder Configuration

Auto-backups are saved to a folder on the server filesystem. The folder path must be an absolute path (starting with /).

  • Use the Browse button to navigate the server filesystem and select a folder
  • Click Validate to confirm the folder exists and is writable
  • A common choice is /backups (see Docker Volume Configuration below)

Folder Browser

Note: The folder must be writable by the backend process. In Docker deployments, you must map a host directory to the container path using a volume mount.

Frequency and Timing

Frequency Description
Every 6 hours Backs up 4 times per day, aligned to the configured backup time
Every 12 hours Backs up twice per day, aligned to the configured backup time
Daily Backs up once per day at the configured time
Weekly Backs up once per week at the configured time

Set the Backup Time to control when backups run (24-hour format, e.g., 02:00 for 2 AM).

The backup time is interpreted in your configured timezone. The timezone is automatically detected from your user preferences.

Retention Policy

Monize uses a three-tier retention system to balance storage usage with backup history:

Tier Default Range Description
Daily 7 0--365 Number of most recent backups to keep
Weekly 4 0--52 One backup per week, kept for this many weeks
Monthly 6 0--120 One backup per month, kept for this many months

How Retention Works

  1. The most recent backups (up to the daily retention count) are always kept
  2. Beyond the daily window, one backup per ISO week is promoted and renamed to a weekly backup
  3. Beyond the weekly window, one backup per calendar month is promoted and renamed to a monthly backup
  4. Files that do not fall into any retention tier are deleted

File Naming

Backup files are automatically named based on their retention tier:

Tier File Name Pattern
Daily monize-backup-YYYY-MM-DDTHH-MM-SS.json.gz
Weekly monize-backup-weekly-WW-YYYY-MM-DDTHH-MM-SS.json.gz
Monthly monize-backup-monthly-MM-YYYY-MM-DDTHH-MM-SS.json.gz

Run Backup Now

Click Run Backup Now to trigger an immediate backup outside of the regular schedule. The backup is saved to the configured folder and follows the same retention rules.

Status Monitoring

Backup Status

The auto-backup section displays the current status:

Field Description
Last Backup Date and time of the most recent backup
Status success or failed
Error Error message if the last backup failed
Next Backup Scheduled time for the next automatic backup

What Is Backed Up

A backup includes all of your financial data across 27 tables:

Category Data Included
Preferences User preferences, currency preferences, auto-backup settings
Accounts All account types and their settings
Transactions Transactions, transaction splits, and associated tags
Scheduled Transactions Recurring bills/deposits, splits, and overrides
Categories & Payees Category hierarchy, payees, and payee aliases
Tags All tags and tag assignments
Investments Securities, security prices, holdings, and investment transactions
Budgets Budgets, budget categories, budget periods, and budget alerts
Reports Custom report definitions
Import Settings Saved column mapping presets
Currencies Currency definitions
Net Worth History Monthly account balance snapshots

Note: User credentials (password, 2FA secrets, trusted devices, refresh tokens) are not included in backups. After restoring on a new server, you will need to log in with your existing credentials.

Backup File Format

Backups are gzip-compressed JSON files with the following structure:

{
  "version": 1,
  "exportedAt": "2026-04-03T02:00:00.000Z",
  "currencies": [...],
  "user_preferences": [...],
  "accounts": [...],
  "transactions": [...],
  ...
}
  • version -- Backup format version (currently 1)
  • exportedAt -- ISO 8601 timestamp of when the backup was created
  • Each table is represented as an array of row objects

Docker Volume Configuration

When running Monize in Docker, the backend container runs with a read-only filesystem for security. To enable auto-backups, you must map a host directory to a container path using a Docker volume.

Add a volume mount to the backend service in your docker-compose.yml:

services:
  backend:
    # ... existing configuration ...
    volumes:
      - /path/on/host/backups:/backups

Then configure /backups as your auto-backup folder path in Monize settings.

Tip: Choose a host path that is included in your server's own backup strategy (e.g., a path covered by your NAS snapshots or cloud sync) for an extra layer of protection.

Security

Backup and restore operations include several security measures:

Measure Description
Authentication All backup operations require a valid login session
Restore verification Restoring requires password re-entry or OIDC re-authentication
User isolation Backups only contain data belonging to the authenticated user
SQL injection prevention Column names are validated against the database schema; all values use parameterized queries
Table allowlist Only the 24 approved data tables can be restored
File size limit Restore files are limited to 100 MB
Path traversal prevention Auto-backup folder paths are validated to prevent directory traversal attacks
Transaction safety Restore runs in a database transaction with full rollback on error
Demo restrictions Restore and auto-backup configuration are disabled in demo mode

Tips and Best Practices

  • Export a backup before major changes -- Before bulk-deleting data, re-importing, or updating Monize, download a manual backup first
  • Test your backups -- Periodically verify that a backup can be restored successfully by restoring on a test instance
  • Use auto-backup with retention -- Enable automatic backups with the default retention settings (7 daily, 4 weekly, 6 monthly) for comprehensive coverage without excessive storage use
  • Map the backup volume to durable storage -- Point your Docker volume at a path that is covered by your server's own backup or sync strategy
  • Keep off-site copies -- Periodically download a manual backup and store it separately from your server (e.g., cloud storage or external drive) for disaster recovery
  • Set a quiet backup time -- Schedule auto-backups during off-peak hours (e.g., 2:00 AM) to minimize any performance impact

Clone this wiki locally