# How to Configure Auto-Backups with Retention Policies in TREK

> Easily configure auto-backups with retention policies in TREK. This guide shows you how to archive your SQLite database and uploads, automatically pruning old backups to save space.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-09

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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:

```javascript
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:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/wiki/Backups.md) documentation.