# How to Update TREK to the Latest Version: Complete Docker Guide

> Easily update TREK to the latest version. This Docker guide shows you how to pull the newest image and recreate containers, preserving all your data for a seamless upgrade.

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

---

**Updating TREK involves pulling the latest `mauriceboe/trek` Docker image and recreating the container, which preserves all data in `./data` and `./uploads` volumes while automatically running database migrations on startup.**

TREK is distributed as a containerized application that keeps user data outside the image. This architecture ensures that upgrading to a newer version never touches your content or configuration, making updates safe and reversible. The process differs slightly depending on whether you use Docker Compose, raw Docker commands, or orchestration tools like Portainer or Proxmox.

## Understanding the Update Architecture

Before executing an update, it is important to understand how TREK handles persistence and versioning.

**Container image tags** determine what version you receive:
- `latest` – Always points to the newest release
- `<major>` (e.g., `3`) – Tracks the newest patch within that major version
- **Full version** (e.g., `3.0.15`) – Pins to a specific release

**Data persistence** relies on bind mounts defined in [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml). The container runs with `read_only: true`, meaning the only writable paths are `./data` mounted to `/app/data` and `./uploads` mounted to `/app/uploads`. Consequently, updating the image only replaces the application code, leaving your database and uploads intact.

**Automatic migrations** run every time the container starts. TREK scans the database schema and applies pending changes without manual intervention. Additionally, if you have not set an `ENCRYPTION_KEY` environment variable, the system automatically migrates `./data/.jwt_secret` to `./data/.encryption_key` on first boot after the upgrade.

## Pre-Update Checklist

Complete these steps before pulling a new image:

1. **Back up your data** using the Admin → Backups interface or manually copy the `./data` and `./uploads` directories.
2. **Note your current tag** in [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) or your `docker run` command to verify the upgrade path.
3. **Verify health endpoint accessibility** at `http://localhost:3000/api/health` to establish a baseline.

## Update Methods

### Docker Compose (Recommended)

For deployments using the official [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml), updating requires a single command if you use the `latest` or major-version tags:

```bash
docker compose pull && docker compose up -d

```

If you prefer to pin to a specific version, edit the `image:` line in [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml):

```yaml
services:
  trek:
    image: mauriceboe/trek:3.0.16

```

Then recreate the container:

```bash
docker compose up -d

```

### Docker Run (Standalone)

For ad-hoc containers started with `docker run`, execute the following sequence:

```bash

# Pull the newest image for your chosen tag

docker pull mauriceboe/trek:latest

# Stop and remove the existing container

docker rm -f trek

# Re-create with identical volume mounts

docker run -d --name trek -p 3000:3000 \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  -e ENCRYPTION_KEY=${ENCRYPTION_KEY:-} \
  --restart unless-stopped \
  mauriceboe/trek:latest

```

### Portainer, Unraid, and Proxmox LXC

UI-driven platforms ultimately execute the same pull-and-restart logic:

- **Portainer / Unraid**: Use the "Redeploy" or "Update" button in the container management interface, ensuring the volume mounts for `./data` and `./uploads` remain unchanged.
- **Proxmox LXC**: Use the community update script:

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/trek.sh)"

```

Select "Update" when prompted to pull the latest image and restart the container.

## Post-Update Verification

Confirm the update succeeded by checking the health endpoint:

```bash
curl -s http://localhost:3000/api/health

```

You should receive `{"status":"ok"}`. If you previously relied on the auto-generated encryption key, verify that `./data/.encryption_key` now exists and contains a valid secret.

Optional: Rotate your encryption key by following the procedure in [`wiki/Encryption-Key-Rotation.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Encryption-Key-Rotation.md) if your security policy requires fresh credentials after major version jumps.

## Summary

- **TREK updates are data-safe** because user content resides in `./data` and `./uploads` volumes outside the container.
- **Choose your image tag** (`latest`, major version, or pinned) to control update frequency.
- **Run `docker compose pull && docker compose up -d`** for the simplest update path.
- **Database migrations and encryption key upgrades** happen automatically on container startup.
- **Always back up** via Admin → Backups before updating to protect against rare filesystem issues.

## Frequently Asked Questions

### Will updating TREK delete my existing data?

No. Because TREK runs in a read-only container with bind-mounted volumes for `./data` and `./uploads`, updating the image only replaces the application binary. Your database, uploaded files, and configuration persist on the host filesystem exactly as they were before the update.

### Do I need to manually run database migrations after updating?

No manual steps are required. According to the TREK source code, the application automatically detects schema versions on startup and executes any pending migrations against the database in `./data`. This process is idempotent and runs every time the container starts.

### What is the difference between the `latest`, `3`, and `3.0.15` image tags?

The `latest` tag always points to the newest stable release, causing your system to update to the next major version automatically. The `3` tag tracks the newest patch within the 3.x series, providing bug fixes without breaking changes. The full version tag `3.0.15` pins your deployment to that specific release, ensuring reproducible environments but requiring manual edits to [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) to upgrade.

### How do I handle the encryption key when updating from older versions?

If you previously used `./data/.jwt_secret` and have not set the `ENCRYPTION_KEY` environment variable, TREK automatically promotes the old secret to `./data/.encryption_key` on the first boot after upgrade. This migration requires no manual intervention. However, if you wish to use a new key, refer to [`wiki/Encryption-Key-Rotation.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Encryption-Key-Rotation.md) for the safe rotation procedure.