TaskTrove Documentation

Appearance

Upgrading TaskTrove ​

This guide covers how to upgrade your TaskTrove installation to the latest version.

Before You Upgrade ​

  1. Backup Your Data: Always create a complete backup of your TaskTrove data before upgrading. See the Backup for detailed instructions.

  2. Review Release Notes: Check the Changelog for any breaking changes or special upgrade instructions for your target version.

Upgrade Methods ​

Docker Installation ​

If you're running TaskTrove with Docker:

bash
# Pull the latest image
docker pull ghcr.io/dohsimpson/tasktrove

# Stop and remove the current container
docker stop tasktrove
docker rm tasktrove

# Start with the new image
docker run -p 3000:3000 -v ./data:/app/data -d --restart=always --name tasktrove ghcr.io/dohsimpson/tasktrove

Docker Compose Installation ​

If you're running TaskTrove with Docker Compose:

bash
# Navigate to your TaskTrove directory
cd TaskTrove/selfhost

# Pull the latest images
docker-compose pull

# Stop current services
docker-compose down

# Start with updated images
docker-compose up -d

Automatic Data Migration ​

Starting from version 0.3.0, TaskTrove includes an automatic data migration system that handles schema changes between versions.

How It Works ​

  1. Detection: When you start TaskTrove after an upgrade, it automatically detects if your data needs migration
  2. Prompt: You'll see a migration dialog explaining what will be changed
  3. Backup: The system creates a timestamped backup file (data.json.backup-[timestamp]) before migrating
  4. Migration: Your data is transformed to work with the new version
  5. Validation: The migrated data is validated to ensure everything is correct

Migration Features ​

  • Safe: Creates automatic backup before migrating
  • Automatic: No manual intervention required in most cases
  • Backup: Creates timestamped backup files for manual recovery if needed

Important Notes ​

  • Manual Backup: While automatic backups are created, manually backing up your data beforehand is recommended
  • One-Way: Once migrated, you cannot use the data with older versions

Version-Specific Notes ​

Upgrading to v0.7.0 or Later ​

Authentication (optional)

Version 0.7.0+ supports optional password protection. If you want to add authentication after upgrading, you must follow these steps in order:

  1. Upgrade to v0.7.0+ without setting the AUTH_SECRET environment variable
  2. Complete data migration in web UI
  3. Set the AUTH_SECRET environment variable to your docker deployment (see installation guide for details)
  4. Restart container
  5. Create a password in web UI

If you set the AUTH_SECRET environment variable before upgrading, you won't be able to blocked by the auth screen. To get unblocked, simply remove the AUTH_SECRET environment variable and restart the container, and complete the data migration first.

API

Version 0.7.0+ supports an experimental API.

Visit the API Documentation for updated endpoint documentation.

Post-Upgrade Steps ​

  1. Complete Migration: If prompted, complete the data migration process
  2. Verify Installation: Confirm TaskTrove is running correctly
  3. Test Core Functionality: Verify that your tasks, projects, and user data are intact
  4. Check Configuration: Review any configuration changes that may be needed
  5. Monitor for Issues: Watch for any errors or performance issues after the upgrade

Troubleshooting ​

If you encounter issues during or after the upgrade, see the Troubleshooting guide or visit our Community Support page.

Downgrade / Rollback ​

If you need to rollback to a previous version after an upgrade:

Using Docker with Versioned Tags ​

bash
# Stop and remove current container
docker stop tasktrove
docker rm tasktrove

# Restore your data backup (if migrated)
cp ./data/data.json.backup-[timestamp] ./data/data.json

# Run with specific version tag
docker run -p 3000:3000 -v ./data:/app/data -d --restart=always --name tasktrove ghcr.io/dohsimpson/tasktrove:v0.2.0

Using Docker Compose ​

Update your docker-compose.yml to specify the version:

yaml
services:
  tasktrove:
    image: ghcr.io/dohsimpson/tasktrove:v0.2.0 # Specify version instead of 'latest'

Then recreate the container:

bash
docker-compose down
docker-compose up -d

Important Notes ​

  • Data Compatibility: If your data was migrated to a newer format, you must restore from a pre-migration backup
  • Version Tags: Available versions can be found on the GitHub releases page