Wiki > Tracearr
Tracearr monitors your Plex, Jellyfin or Emby server. It shows who is streaming what in real time, keeps playback history and statistics, and can detect shared accounts, for example the same account streaming from two cities at once.
This article runs Tracearr's all-in-one container image with rootless Podman. The image includes the PostgreSQL (TimescaleDB) database and Redis that Tracearr needs.
16871 was randomly generated for this article; you may use any 5-digit port between 10000 and 32767.
Installation
-
Connect to your slot via SSH.
-
Create the folders for Tracearr and its data:
mkdir -p ~/tracearr/data/postgres ~/tracearr/data/redis ~/tracearr/data/tracearr ~/tracearr/data/backup -
Create the settings file. It holds a claim code, which anyone setting up Tracearr must enter, so nobody else can take over your install before you do:
echo "CLAIM_CODE=$(openssl rand -hex 8)" > ~/tracearr/.env && chmod 600 ~/tracearr/.env -
Create the Compose file:
nano ~/tracearr/compose.yaml -
Paste in the following. Change
TZto your time zone:services: tracearr: image: ghcr.io/connorgallopo/tracearr:supervised container_name: tracearr restart: unless-stopped env_file: - .env ports: - "127.0.0.1:16871:3000" volumes: - /home/user/tracearr/data/postgres:/data/postgres - /home/user/tracearr/data/redis:/data/redis - /home/user/tracearr/data/tracearr:/data/tracearr - /home/user/tracearr/data/backup:/data/backup shm_size: 512mb ulimits: nofile: soft: 65536 hard: 65536 environment: - TZ=America/Toronto - TRUST_PROXY=true - PG_MAX_MEMORY=1GB - NODE_OPTIONS=--max-old-space-size=768 userns_mode: "keep-id:uid=1001,gid=1001"Save with
Ctrl + Sand exit withCtrl + X.PG_MAX_MEMORYandNODE_OPTIONSkeep the database and Tracearr to a sensible amount of memory. Theuserns_modeline makes Tracearr's own files and backups belong to your account.127.0.0.1keeps Tracearr reachable only through Managed Links. -
Start Tracearr:
cd ~/tracearr && podman-compose up -dThe first start downloads a 2.8 GB image and prepares it, which can take five minutes or more before the command returns.
-
Tracearr then sets up its database. It's ready when this prints
200:curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:16871/healthIf it prints
000or503, wait a little and run it again. You can read the startup log withpodman logs tracearr. -
On the Manage Links page, click Add a custom app. Name it
tracearr, enter port16871, and open Advanced options to enable WebSockets. -
Show your claim code:
grep CLAIM_CODE ~/tracearr/.env -
Visit https://tracearr.example.box.ca, enter the claim code, and sign in with your Plex, Jellyfin or Emby account to create the owner account.
Configuration
Configure Tracearr from its web interface. See the Tracearr documentation for each page.
- Media server address: for a Jellyfin or Plex server on your slot, use its Managed Link, for example
https://app.example.box.ca. The link must exist before Tracearr starts: if you add it later, restart Tracearr withcd ~/tracearr && podman-compose down && podman-compose up -d. Tracearr runs in a container, soserver.whatbox.caaddresses don't work from it. - Jellyfin and Emby live statistics: install the Media Server SSE plugin on your media server.
- Importing history: Tracearr can import from Tautulli (Plex), a Jellystat backup, or the Playback Reporting plugin (Jellyfin and Emby).
Files in the data folder
Tracearr's settings, image cache and backups in ~/tracearr/data/tracearr and ~/tracearr/data/backup belong to your account. The database in ~/tracearr/data/postgres and ~/tracearr/data/redis belongs to the container's own users, so your account can't read, change or delete those folders directly. Prefix commands with podman unshare to work with them, for example:
podman unshare du -sh ~/tracearr/data
Automatically Restart (optional)
Rootless containers don't start again by themselves after the server reboots. This script starts Tracearr if it isn't running.
-
Create a restart script:
touch ~/tracearr_restart.cron nano -w ~/tracearr_restart.cron -
Paste in the following:
#!/bin/bash if [ -n "$(podman ps -q --filter name='^tracearr$' --filter status=running)" ] then echo "Tracearr is running." else echo "Tracearr is not running, starting Tracearr" podman start tracearr fi exitSave and exit.
-
Make the script executable:
chmod +x ~/tracearr_restart.cron -
Open your crontab:
EDITOR=nano crontab -e -
Add these lines, then save and exit:
@reboot /home/user/tracearr_restart.cron >/dev/null 2>&1 */5 * * * * /home/user/tracearr_restart.cron >/dev/null 2>&1
Updating
Tracearr upgrades its database automatically the first time a new version starts. Don't stop it while it's doing this.
-
Make a copy of your data while Tracearr is stopped:
cd ~/tracearr && podman-compose down podman unshare tar czf ~/tracearr-backup.tar.gz -C ~/tracearr data .env -
If you set up the restart script, comment out its two lines in your crontab (
EDITOR=nano crontab -e) so it doesn't start Tracearr mid-update. -
Download the new image and start Tracearr again:
cd ~/tracearr podman-compose pull podman-compose up -d -
Wait until the
curlcommand from step 7 of Installation prints200, then uncomment the crontab lines. Once everything works, you can delete~/tracearr-backup.tar.gz.
Uninstalling
This deletes your Tracearr history and settings. Your media server isn't touched.
-
Remove the two
tracearr_restart.cronlines from your crontab (EDITOR=nano crontab -e). -
Stop and remove the container, then delete Tracearr's files:
cd ~/tracearr && podman-compose down && cd ~ podman unshare rm -rf ~/tracearr rm -f ~/tracearr_restart.cron podman rmi ghcr.io/connorgallopo/tracearr:supervised -
Delete the
tracearrlink from the Manage Links page.
Troubleshooting
- https://tracearr.example.box.ca doesn't load: check Tracearr is running (the
curlcommand from step 7 of Installation prints200) and the Managed Link uses port 16871 with WebSockets enabled. - Setup asks for a claim code: it's the
CLAIM_CODEline in~/tracearr/.env(step 9 of Installation). - Tracearr can't connect to your media server: use the server's Managed Link address, not
server.whatbox.ca. If you created the link after starting Tracearr, runpodman-compose downandpodman-compose up -dfrom~/tracearr. - "Permission denied" when reading or deleting files in
~/tracearr/data: the database folders belong to the container's users. Prefix the command withpodman unshare. - The restart script starts a second copy, or never starts Tracearr: check the
podman psline intracearr_restart.cronmatches the one above exactly, including'^tracearr$'. - Containers won't stop or start: run
podman-compose downfrom~/tracearr, thenpodman-compose up -d. - Anything else: Tracearr's own logs are inside the container; read them with
podman exec tracearr tail -n 50 /var/log/supervisor/tracearr.log. See the Tracearr documentation, or ask on Tracearr's Discord.