How to Configure Auto-Backups with Retention Policies in TREK

TREK provides a built-in auto-backup feature that periodically archives your SQLite database and uploads directory into ZIP files, with configurable retention policies that automatically prune backups older than a specified number of days.

The open-source TREK travel management platform (mauriceboe/TREK) includes a comprehensive backup system that protects your data through scheduled ZIP archives and automated cleanup routines. This guide explains how to configure auto-backups with retention policies using both the administrative interface and the REST API, based on the actual implementation in the source code.

Understanding the Auto-Backup Architecture

TREK's backup system consists of several coordinated components that handle creation, storage, and lifecycle management.

Core Components

The Backup controller at server/src/nest/backup/backup.controller.ts exposes HTTP endpoints under /api/backup/* that manage manual creation, restoration, and auto-backup settings. The Backup service in shared/src/backup/backup.schema.ts implements the core logic for creating ZIP archives and pruning old files. A scheduler (located in src/nest/backup/backup.scheduler.ts) runs once per minute to check if it's time to trigger a backup based on your configured schedule.

Auto-backups are stored in data/backups/ alongside manual backups, with filenames following the pattern auto-backup-<timestamp>.zip to distinguish them from manually created backup-<timestamp>.zip files.

Configuring Retention Policies

The retention mechanism controls how long backup files persist before automatic deletion.

The keep_days Parameter

The retention policy centers on the keep_days integer field (default: 7 days). After each scheduled backup run completes, the system calculates a cutoff timestamp and removes any backup files—both manual and automatic—older than the specified threshold. Setting keep_days to 0 disables pruning entirely, preserving all backups indefinitely.

This logic resides in the backup service, which evaluates the timestamp of each file in data/backups/ against the configured retention window.

Setting Up Auto-Backups via the Admin Panel

Configure your backup schedule through the web interface without writing code.

1. Navigate to Admin → Backups.

2. In the Auto-Backup section, toggle Enabled.

3. Configure the schedule parameters:

   • Hour: 0-23 (UTC time when the backup runs)
   • Day of week: 0-6 for weekly backups (Sunday=0, Saturday=6)
   • Day of month: 1-28 for monthly backups (values above 28 are ignored)
   • Retention – Keep last … days: Number of days to retain backups (use 0 for permanent retention)

4. Click Save to persist the settings to the database.

The front-end components in the UI (located in src/ui/backup/) send a POST request to /api/backup/auto_settings with your configuration.

Automating Configuration via the REST API

Programmatically manage auto-backups using the REST API endpoints defined in backup.controller.ts.

Endpoint Specification

Method	Endpoint	Description
POST	/api/backup/auto_settings	Create or update auto-backup configuration
GET	/api/backup/auto_settings	Retrieve current settings
DELETE	/api/backup/auto_settings	Disable auto-backup

Node.js Example

Use the API client or direct HTTP calls to configure auto-backups:

import axios from 'axios';

const api = axios.create({ 
  baseURL: 'https://your-trek-instance.com/api', 
  withCredentials: true 
});

async function configureAutoBackup() {
  await api.post('/backup/auto_settings', {
    enabled: true,
    hour: 3,          // Run at 03:00 UTC
    dayOfWeek: 0,     // Weekly on Sunday
    dayOfMonth: 1,    // Monthly on the 1st
    keepDays: 30      // Retain for 30 days
  });
  console.log('Auto-backup configured with 30-day retention');
}

configureAutoBackup().catch(console.error);

cURL Example

Configure via command line:

curl -X POST \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"hour":2,"dayOfWeek":0,"dayOfMonth":1,"keepDays":14}' \
  https://your-trek-instance.com/api/backup/auto_settings

How Retention Pruning Works Under the Hood

The scheduler executes retention logic immediately after creating each scheduled backup.

Execution Flow

When the scheduler determines it's time to run (based on matching the current hour/day against your settings), it triggers createBackup() in the backup service. After successful creation, the system checks if keepDays > 0. If so, it calculates a cutoff timestamp (Date.now() - keepDays * 24 * 60 * 60 * 1000) and iterates through all files in data/backups/, deleting any with timestamps older than the cutoff.

Each deletion is logged to the audit system with action: "backup.delete", similar to how creations are logged with action: "backup.create".

File Structure

Backups include:

• travel.db: The SQLite database
• uploads/: User-uploaded content

Important: Backups do not contain the ENCRYPTION_KEY. You must back up this key separately according to the wiki/Backups.md documentation.

Troubleshooting Common Issues

Symptom	Cause	Solution
Backups not pruning	keepDays set to 0 or negative	Set a positive integer (e.g., 14) in the retention field
Upload fails with 413 error	Reverse proxy limit below 500 MiB	Increase client_max_body_size to at least 500m in nginx/Caddy
Auto-backup never executes	Timezone mismatch or scheduler not running	Verify server timezone and check logs for BackupScheduler startup
Missing uploads in backup	Directory permissions incorrect	Ensure uploads/ is writable by the container process
Restore fails	ENCRYPTION_KEY missing from backup	Back up the encryption key separately from the ZIP files

Summary

• Auto-backups in TREK are managed by a cron-like scheduler that reads settings from the backup_auto_settings table.
• The keep_days parameter controls retention, automatically deleting files older than the specified threshold after each backup run.
• Configure via Admin → Backups or through POST /api/backup/auto_settings with parameters for hour, day of week, day of month, and retention days.
• Files are stored in data/backups/ as auto-backup-<timestamp>.zip and include travel.db and the uploads/ directory.
• The system respects the BACKUP_UPLOAD_LIMIT_MB environment variable (default 500 MiB) and requires corresponding reverse-proxy configuration.
• All actions generate audit logs with actions backup.create, backup.auto_settings, and backup.delete.

Frequently Asked Questions

How do I disable automatic backup pruning while keeping the scheduled backups?

Set the Retention – Keep last … days field to 0 in the Admin panel, or send "keepDays": 0 via the API. This disables the pruning logic entirely, causing TREK to retain all backup files indefinitely. Note that this will consume increasing disk space over time.

What happens if my backup file exceeds the 500 MiB limit?

The server rejects uploads exceeding the BACKUP_UPLOAD_LIMIT_MB environment variable (default 500 MiB). For restoration, ensure your reverse proxy (nginx, Caddy, etc.) allows large payloads by setting client_max_body_size appropriately. For creation, the system automatically packages your database and uploads without size checks, though very large uploads/ directories may require manual backup strategies.

Can I schedule multiple backups per day?

No, the current scheduler implementation in backup.scheduler.ts supports only hourly precision within a single daily, weekly, or monthly slot. You specify one hour (0-23) when the backup runs. For more frequent backups, you would need to modify the scheduler or use external cron jobs hitting the manual backup endpoint.

Why does my restored backup fail to decrypt data?

The ZIP archives created by TREK intentionally exclude the ENCRYPTION_KEY for security reasons. When restoring, you must provide the original encryption key separately. Always back up your ENCRYPTION_KEY environment variable or file separately from the automated backups, as noted in the wiki/Backups.md documentation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}