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

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. 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 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, updating requires a single command if you use the latest or major-version tags:

docker compose pull && docker compose up -d

If you prefer to pin to a specific version, edit the image: line in docker-compose.yml:

services:
  trek:
    image: mauriceboe/trek:3.0.16

Then recreate the container:

docker compose up -d

Docker Run (Standalone)

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

# 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 -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:

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 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 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 for the safe rotation procedure.

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