tunarr/docs/configure/system/backup.md

Backup & Restore

Tunarr provides a backup system that creates compressed archives of your configuration, database, and media assets. Backups can be scheduled to run automatically or triggered manually.

What Gets Backed Up

A Tunarr backup archive includes:

Item	Description
db.db	SQLite database containing channels, programs, and configuration
settings.json	System settings and media source configurations
channel-lineups/	Channel lineup data and M3U files
images/	Channel logos, artwork, and thumbnails
cache/	Cached subtitles, posters, banners, fanart, and watermarks
ms-snapshots/	Meilisearch index snapshots (optional)
*.xml	XMLTV output files

Configuration

Backup settings can be configured in the Tunarr web UI under Settings > System > Backup, or via the API.

Backup Options

Option	Default	Description
Enabled	true	Enable or disable scheduled backups
Schedule	Daily at 4:00 AM	When to run automatic backups
Output Path	{data directory}/backups/	Where backup files are stored
Archive Format	tar	Archive format: tar or zip
Gzip Compression	false	Enable gzip compression (tar only)
Max Backups	3	Number of backups to retain before deleting oldest

File Naming

Backup files are named using a timestamp format:

tunarr-backup-YYYYMMDD_HHmmss.tar
tunarr-backup-YYYYMMDD_HHmmss.tar.gz  (with gzip)
tunarr-backup-YYYYMMDD_HHmmss.zip

Example: tunarr-backup-20250118_040000.tar.gz

Scheduling

Backups can be scheduled in two ways:

Interval-Based

Run backups at regular intervals:

• Every N hours
• Every N days

Example: "Every 1 day at 4:00 AM"

Cron-Based

Use a cron expression for more complex schedules:

0 4 * * *    # Daily at 4:00 AM
0 */6 * * *  # Every 6 hours
0 4 * * 0    # Weekly on Sunday at 4:00 AM

Manual Backup

Via Web UI

Navigate to Settings > System > Backup and click the Backup Now button.

Via API

Trigger a backup using the tasks API:

curl -X POST "http://localhost:8000/api/tasks/BackupTask/run"

To run the backup in the background (recommended for large installations):

curl -X POST "http://localhost:8000/api/tasks/BackupTask/run?background=true"

Backup Retention

When a new backup is created and the total number of backups exceeds the maxBackups setting, the oldest backups are automatically deleted. This helps prevent disk space from filling up over time.

Restore

!!! warning "Manual Process" Tunarr does not currently have a built-in restore feature. Restoration must be done manually.

Restore Steps

1. Stop Tunarr - Ensure the Tunarr server is not running

2. Locate your data directory:

   • Docker: The path you mounted to /config/tunarr
   • Windows: %APPDATA%\tunarr
   • macOS: ~/Library/Preferences/tunarr
   • Linux: ~/.local/share/tunarr

3. Extract the backup archive:

   # For tar archives
   tar -xvf tunarr-backup-YYYYMMDD_HHmmss.tar -C /path/to/restore/
   
   # For gzipped tar archives
   tar -xzvf tunarr-backup-YYYYMMDD_HHmmss.tar.gz -C /path/to/restore/
   
   # For zip archives
   unzip tunarr-backup-YYYYMMDD_HHmmss.zip -d /path/to/restore/
   

4. Copy files to the data directory:

   # Required files
   cp /path/to/restore/db.db /path/to/tunarr/data/
   cp /path/to/restore/settings.json /path/to/tunarr/data/
   
   # Optional directories (restore as needed)
   cp -r /path/to/restore/images/ /path/to/tunarr/data/
   cp -r /path/to/restore/cache/ /path/to/tunarr/data/
   cp -r /path/to/restore/channel-lineups/ /path/to/tunarr/data/
   

5. Start Tunarr - The search index will rebuild automatically if not restored

Docker Restore Example

# Stop the container
docker stop tunarr

# Extract backup to a temporary location
tar -xzvf tunarr-backup-20250118_040000.tar.gz -C /tmp/tunarr-restore/

# Copy to your mounted volume
cp /tmp/tunarr-restore/db.db /path/to/tunarr/data/
cp /tmp/tunarr-restore/settings.json /path/to/tunarr/data/

# Start the container
docker start tunarr

Excluding Search Snapshots

Meilisearch index snapshots can be large. To exclude them from backups, set the environment variable:

TUNARR_DISABLE_SEARCH_SNAPSHOT_IN_BACKUP=true

When restoring a backup without search snapshots, Tunarr will automatically rebuild the search index on startup. This may take a few minutes depending on your library size.

!!! warning "Windows Snapshots" There is currently an issue in Meilisearch where snapshots do not work correctly on Windows. Until this is resolved, Windows users should disable Meilisearch snapshots.

Excluding data.ms from Proxmox Backup Server

The data.ms directory contains the Meilisearch search index and can be several gigabytes in size. Since Tunarr rebuilds this index automatically on startup, there is no need to include it in Proxmox Backup Server (PBS) jobs.

PBS uses .pxarexclude files (similar to .gitignore) to exclude paths from backups. To exclude data.ms, create or edit a .pxarexclude file in your Tunarr data directory:

# Create .pxarexclude in the Tunarr data directory
# Docker example — adjust to your actual mount path
echo "data.ms/" >> /path/to/tunarr/data/.pxarexclude

The file should contain:

data.ms/

PBS will skip the data.ms directory during all future backup jobs that include that path. No PBS job reconfiguration is required — the exclusion is applied automatically when PBS encounters the .pxarexclude file.

Backup Storage Locations

Default Location

Backups are stored in the backups/ subdirectory of your Tunarr data directory:

Platform	Default Path
Docker	/config/tunarr/backups/
Windows	%APPDATA%\tunarr\backups\
macOS	~/Library/Preferences/tunarr/backups/
Linux	~/.local/share/tunarr/backups/

Custom Location

You can configure a custom output path in the backup settings to store backups on a different drive or network location.

Best Practices

1. Test your backups - Periodically verify that backups can be restored successfully
2. Store backups off-site - Copy backups to cloud storage or another machine
3. Monitor disk space - Ensure your backup location has sufficient free space
4. Adjust retention - Increase maxBackups if you need more recovery points
5. Schedule during off-hours - Run backups when Tunarr is less active to minimize impact