Upgrading

Tracearr uses the latest Docker image tag by default, so upgrading is straightforward — pull the new image and recreate the container.

TimescaleDB and Redis are persisted in a volume, so your database and configuration will be preserved during the upgrade process.

Authentication Changes

1.5.0 replaced Tracearr’s authentication system. The upgrade itself requires nothing from you: no new environment variables are needed, and database migrations run automatically when the new version starts. What changes:

1. Jellyfin login was removed in 1.5.0. From 1.5.0 to 2.7.x nobody could sign in to Tracearr with Jellyfin credentials; 2.8.0 brings it back through member sign-in (see below). If your install only ever logged in via Jellyfin, recover with either:

   • the admin CLI: docker exec -it tracearr node apps/server/dist/scripts/cli.js reset-password (works even when the account has no existing password), or
   • Sign in with Plex, when a Plex account is linked.

   See Account Recovery for details.

2. All web users must log in once after upgrading. Existing web sessions are not carried over.

3. Mobile devices paired after upgrading use a 30-day rolling session. Any use within 30 days extends it; a device idle for more than 30 days pairs again. Devices paired before the upgrade keep working on their existing tokens until they are re-paired; nothing expires them at 30 days.

2.8.0: member sign-in

The people you share a server with can sign in with their Plex, Jellyfin or Emby account; see Member sign-in. The upgrade itself asks nothing of you: no new environment variables, and the migration runs on start. What changes for existing installs:

1. Everyone except the owner is a member. Admin accounts become members. Settings → Access → Guest access is now Sign-in, with a switch for each sign-in method, and member sign-in starts off. Allow Guest Access is gone.
2. Jellyfin sign-in is back, and Emby sign-in is new. It is for admins and members, and the owner’s own account works too, on a server with member sign-in on.
3. TRUST_PROXY=true trusts one proxy hop. The client address is the one your proxy appended to X-Forwarded-For, and X-Forwarded-Host is honored only when proxies are trusted. Two chained proxies need TRUST_PROXY=2, or a list of proxy IPs or CIDR ranges. A proxy that rewrites Host now needs TRUST_PROXY set so its X-Forwarded-Host is honored; listing the public URL in CORS_ORIGIN instead fixes password sign-in but not SSO. The value is checked on start: true, false, digits, or IPs and CIDR ranges; a value like yes that used to be ignored now stops the server with an error naming TRUST_PROXY.
4. Only Tracearr’s own address and the origins listed in CORS_ORIGIN can use a signed-in session. Before 2.8.0 an unset CORS_ORIGIN let any origin make requests with your session. The web app on Tracearr’s own address needs nothing in CORS_ORIGIN. A page on another origin, such as another port or subdomain, now gets “This request did not come from Tracearr” on writes until its origin is listed. * only allows requests without a session, such as the public API with an API key.

Docker Compose

This guide assumes you followed the Quick Start instructions to set up Tracearr with Docker Compose.

From the directory containing your docker-compose.pg18.yml file, run:

docker compose -f docker-compose.pg18.yml pull tracearr
docker compose -f docker-compose.pg18.yml up -d

This will:

1. Download the latest Tracearr image
2. Recreate the container with the new image
3. Preserve your database and configuration

Docker UI

If you deployed Tracearr through a Docker UI like Portainer, Dockge, or TrueNAS’s built-in Custom App feature, look for an option to re-pull images or redeploy your stack. The exact label varies by tool — see the Docker UI updating guide for details.

Supervised

From the directory containing your docker-compose.supervised-example.yml file, run:

docker compose -f docker-compose.supervised-example.yml pull tracearr
docker compose -f docker-compose.supervised-example.yml up -d

Railway

Railway supports both automatic and manual updates. See the Railway updating guide for how to configure auto-updates or manually trigger an upgrade from the dashboard.

Proxmox VE

If you installed Tracearr using the Proxmox VE community helper script , you can update by logging into the Tracearr LXC container console and running:

update

This command is created automatically during installation. It pulls the latest version of the update script from the community-scripts repository, checks for a newer release, and applies the update.

You can also update all community-script containers at once from the Proxmox host shell using the update-apps  tool.

Unraid

In the Unraid web UI, go to the Docker tab, find Tracearr, and click Check for Updates or Update. Unraid will pull the latest image and recreate the container.

Cleaning Up Old Images

After upgrading, you can remove unused images to free up disk space:

docker image prune