Whatbox Logo
Login for certain variables to be updated with your slot's information

Wiki > Tracearr

Whatbox has limited support for containers; they may stop working at any time.

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

  1. Connect to your slot via SSH.

  2. Create the folders for Tracearr and its data:

     mkdir -p ~/tracearr/data/postgres ~/tracearr/data/redis ~/tracearr/data/tracearr ~/tracearr/data/backup
    
  3. 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
    
  4. Create the Compose file:

     nano ~/tracearr/compose.yaml
    
  5. Paste in the following. Change TZ to 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 + S and exit with Ctrl + X.

    PG_MAX_MEMORY and NODE_OPTIONS keep the database and Tracearr to a sensible amount of memory. The userns_mode line makes Tracearr's own files and backups belong to your account. 127.0.0.1 keeps Tracearr reachable only through Managed Links.

  6. Start Tracearr:

     cd ~/tracearr && podman-compose up -d
    

    The first start downloads a 2.8 GB image and prepares it, which can take five minutes or more before the command returns.

  7. 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/health
    

    If it prints 000 or 503, wait a little and run it again. You can read the startup log with podman logs tracearr.

  8. On the Manage Links page, click Add a custom app. Name it tracearr, enter port 16871, and open Advanced options to enable WebSockets.

  9. Show your claim code:

     grep CLAIM_CODE ~/tracearr/.env
    
  10. 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 with cd ~/tracearr && podman-compose down && podman-compose up -d. Tracearr runs in a container, so server.whatbox.ca addresses 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.

  1. Create a restart script:

     touch ~/tracearr_restart.cron
     nano -w ~/tracearr_restart.cron
    
  2. 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
     exit
    

    Save and exit.

  3. Make the script executable:

     chmod +x ~/tracearr_restart.cron
    
  4. Open your crontab:

     EDITOR=nano crontab -e
    
  5. 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.

  1. 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
    
  2. 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.

  3. Download the new image and start Tracearr again:

     cd ~/tracearr
     podman-compose pull
     podman-compose up -d
    
  4. Wait until the curl command from step 7 of Installation prints 200, 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.

  1. Remove the two tracearr_restart.cron lines from your crontab (EDITOR=nano crontab -e).

  2. 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
    
  3. Delete the tracearr link from the Manage Links page.

Troubleshooting

  • https://tracearr.example.box.ca doesn't load: check Tracearr is running (the curl command from step 7 of Installation prints 200) and the Managed Link uses port 16871 with WebSockets enabled.
  • Setup asks for a claim code: it's the CLAIM_CODE line 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, run podman-compose down and podman-compose up -d from ~/tracearr.
  • "Permission denied" when reading or deleting files in ~/tracearr/data: the database folders belong to the container's users. Prefix the command with podman unshare.
  • The restart script starts a second copy, or never starts Tracearr: check the podman ps line in tracearr_restart.cron matches the one above exactly, including '^tracearr$'.
  • Containers won't stop or start: run podman-compose down from ~/tracearr, then podman-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.