TaskTrove Documentation

Appearance

Backup ​

This guide covers how to backup and restore your TaskTrove data to ensure your tasks and projects are always safe. TaskTrove now includes a built-in automatic backup system for effortless daily backups.

⚠️ Important Disclaimer
You are solely responsible for backing up your data. TaskTrove and its developers are not liable for any data loss, corruption, or damages that may occur. Always test your backup and restore procedures regularly, and maintain multiple backup copies in different locations. Use this software at your own risk.

Understanding TaskTrove Data Storage ​

TaskTrove stores all your data in a simple data directory structure:

  • Location: ./data (mounted to /app/data inside the container)
  • Format: Simple JSON files for easy portability
  • Privacy: All data stays on your server

Backup Methods ​

Important: Auto backup is disabled by default. You must enable it to start automatic daily backups.

TaskTrove includes a built-in automatic backup system that creates daily backups without any external setup:

Features:

  • Automatic: Runs daily at your configured time (default: 2:00 AM server time)
  • Opt-in: Auto backup is disabled by default - enable via Settings for automatic backups
  • Configurable: Enable/disable, set backup time, and configure retention policy via Settings
  • Smart Rotation: Automatically removes old backups based on your preferences
  • Manual Trigger: Create backups on-demand via the UI
  • Zero Configuration: Works out of the box with no external dependencies

Docker Volume Mounting (Required for Auto Backup):

⚠️ Important: To use auto backup with Docker, you must mount the backups directory as a volume to access backup files from your host system.

Update your Docker run command to include both data and backups volumes:

bash
# Standard setup with auto backup support
docker run -p 3000:3000 \
  -v ./data:/app/data \
  -v ./backups:/app/backups \
  -d --restart=always --name tasktrove \
  ghcr.io/dohsimpson/tasktrove

Or with docker-compose:

yaml
version: '3.8'
services:
  tasktrove:
    image: ghcr.io/dohsimpson/tasktrove
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./backups:/app/backups
    restart: always

How to Configure:

  1. Open TaskTrove Settings → Import & Export
  2. Toggle "Enable Auto Backup" to ON (this is disabled by default)
  3. Set "Backup Time" (when auto backup is enabled):
    • Use 24-hour format (e.g., 02:00 for 2:00 AM, 16:30 for 4:30 PM)
    • Choose any time that works for your schedule
    • Default: 02:00 (2:00 AM)
  4. Set "Maximum Backups to Keep":
    • Choose from 3, 5, 7, 10, 14, 21, 30, 90, 365 backups
    • Select "No limit" for unlimited backups (no automatic deletion) - this is the default setting
  5. Click "Trigger Manual Backup Now" to create an immediate backup

Directory Structure:

tasktrove/
├── data/           # Your TaskTrove data files
├── backups/        # Auto-generated backup files (ZIP format)
└── docker-compose.yml

Backup Location:

  • Directory: ./backups/ (next to your data directory)
  • Format: Compressed ZIP files named backup-YYYY-MM-DD_HH-mm-ss.zip
  • Contents: Complete data/ directory including all tasks, projects, labels, and settings

Backup Rotation:

  • Automatic cleanup keeps only your specified number of backups
  • Oldest backups are deleted first when the limit is exceeded
  • Set to "No limit" (-1) to disable automatic cleanup

Manual Backups: You can trigger manual backups anytime through:

  • Settings UI: "Trigger Manual Backup Now" button
  • API endpoint: POST /api/backup (useful for scripts)

Method 1: Simple Directory Copy ​

The easiest way to backup TaskTrove is to copy the entire data directory:

bash
# Stop TaskTrove container (optional but recommended)
docker stop tasktrove

# Copy the data directory to your backup location
cp -r ./data /path/to/your/backup/tasktrove-backup-$(date +%Y%m%d)

# Restart TaskTrove
docker start tasktrove

Method 2: Tar Archive ​

Create a compressed backup archive:

bash
# Create a timestamped backup archive
tar -czf tasktrove-backup-$(date +%Y%m%d-%H%M%S).tar.gz ./data

# Verify the backup
tar -tzf tasktrove-backup-*.tar.gz

Method 3: Automated Backup Script ​

Create a simple backup script for regular backups:

bash
#!/bin/bash
# backup-tasktrove.sh

BACKUP_DIR="/path/to/backups"
DATE=$(date +%Y%m%d-%H%M%S)
BACKUP_NAME="tasktrove-backup-$DATE.tar.gz"

# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"

# Create backup
tar -czf "$BACKUP_DIR/$BACKUP_NAME" ./data

# Keep only last 7 backups (optional)
cd "$BACKUP_DIR" && ls -t tasktrove-backup-*.tar.gz | tail -n +8 | xargs rm -f

echo "Backup completed: $BACKUP_NAME"

Make it executable and add to cron:

bash
chmod +x backup-tasktrove.sh
# Add to crontab for daily backup at 2 AM
0 2 * * * /path/to/backup-tasktrove.sh

Backup Best Practices ​

  1. Enable Built-in Auto Backup: Auto backup is disabled by default - enable it in Settings → Import & Export to set up daily automatic backups as your primary backup method
  2. Choose Appropriate Retention:
    • Default: Unlimited backups (no automatic deletion) - suitable for most users
    • Storage-conscious: 7-30 backups (1 week to 1 month) if disk space is limited
    • Long-term archival: 90-365 backups (3 months to 1 year) for compliance needs
  3. Supplement with Manual Backups: Create additional backups before major changes or updates

Frequency ​

  • Built-in Auto: Daily at your configured time (automatic, recommended)
  • Manual Backups: Before updates, major changes, or data imports
  • External Backups: Weekly/monthly copies to external storage

Backup Timing Considerations ​

When choosing your backup time, consider:

  • Off-Peak Hours: Schedule during low-usage periods (typically 02:00-05:00)
  • Server Timezone: Backup time uses server timezone, not your local time
  • System Resources: Backups use CPU and I/O - avoid peak usage times
  • Maintenance Windows: Coordinate with any scheduled maintenance
  • User Activity: Choose times when users are least active on the system

Common Backup Times:

  • 02:00 - Traditional choice, minimal user activity
  • 03:00 - Alternative early morning option
  • 01:30 - Before typical maintenance windows
  • 23:00 - Late evening option for some timezones

Storage Locations ​

  • Built-in: Automatic backups stored in ./backups/ directory (local)
  • External: Copy auto-generated ZIP files to additional drives or external storage
  • Cloud: Upload backup ZIP files to cloud storage services
  • Remote: Copy backups to another server or NAS

Verification ​

Always verify your backups work:

bash
# Test auto backup ZIP file
unzip -t backups/backup-*.zip && echo "Auto backup ZIP is valid"

# Test manual tar backup
tar -tzf tasktrove-backup-*.tar.gz >/dev/null && echo "Backup archive is valid"

Restoring from Backup ​

From Built-in Auto Backup ​

bash
# Stop TaskTrove
docker stop tasktrove

# Navigate to backup directory
cd backups

# List available backups (newest first)
ls -t backup-*.zip

# Extract the desired backup (replace filename with your chosen backup)
unzip backup-2024-01-15_02-00-00.zip -d ../

# This creates a 'data' folder with your backed up data
# Start TaskTrove
docker start tasktrove

From Directory Copy ​

bash
# Stop TaskTrove
docker stop tasktrove

# Replace current data with backup
rm -rf ./data
cp -r /path/to/backup/data ./data

# Start TaskTrove
docker start tasktrove

From Tar Archive ​

bash
# Stop TaskTrove
docker stop tasktrove

# Remove current data and extract backup
rm -rf ./data
tar -xzf tasktrove-backup-*.tar.gz

# Start TaskTrove
docker start tasktrove

Migration to New Server ​

To move TaskTrove to a new server:

  1. Create backup on old server:

    bash
    tar -czf tasktrove-migration.tar.gz ./data

  2. Transfer backup to new server:

    bash
    scp tasktrove-migration.tar.gz user@newserver:/path/to/tasktrove/

  3. Install TaskTrove on new server (see Installation)

  4. Restore data before first run:

    bash
    tar -xzf tasktrove-migration.tar.gz
docker run -p 3000:3000 -v ./data:/app/data -v ./backups:/app/backups -d --restart=always --name tasktrove ghcr.io/dohsimpson/tasktrove

Troubleshooting ​

Auto Backup Issues ​

  • Not Running: Auto backup is disabled by default - check that you've enabled it in Settings → Import & Export
  • Missing Backup Volume: If using Docker, ensure you've mounted the backups directory: -v ./backups:/app/backups
  • Missing Backups: Verify TaskTrove container is running continuously at your configured backup time
  • Wrong Time: Backup time is based on server timezone - adjust backup time setting if needed
  • Time Format: Ensure backup time is in valid 24-hour format (HH:MM, e.g., 14:30)
  • Backup Directory: Ensure ./backups/ directory is writable by the TaskTrove container
  • Disk Space: Auto backups will fail if insufficient disk space is available
  • Manual Trigger: Use "Trigger Manual Backup Now" button to test the backup system
  • Logs: Check TaskTrove container logs for backup error messages

Manual Backup Issues ​

  • Permissions: Ensure you have read access to the data directory
  • Disk Space: Check available space before creating backups
  • Container Running: Some file systems may have issues if TaskTrove is actively writing

Restore Issues ​

  • File Permissions: Ensure the restored data directory has correct permissions
  • Container Restart: Always restart TaskTrove after restoring data
  • Validation: Check TaskTrove logs if data doesn't appear after restore

Security Considerations ​

  • Backup Security: Your backups contain all your task data - store them securely
  • Encryption: Consider encrypting backups if storing in untrusted locations
  • Access Control: Limit access to backup files and directories

Since TaskTrove stores data in simple JSON files, your backups are portable and future-proof, ensuring you'll always have access to your data regardless of software changes.