Tracearr Setup Guide: Real-Time Monitoring for Plex, Jellyfin, and Emby
Tracearr is the observability layer for a media homelab. Plex, Jellyfin, and Emby show people media. Sonarr and Radarr manage library intent. Tdarr optimizes files. Tracearr answers the operator question that comes after all of that: what is actually happening right now, who is watching, what is transcoding, where are streams coming from, and what patterns deserve review?
This guide focuses on a native Ubuntu source install with systemd, PostgreSQL/TimescaleDB, and Redis. Upstream Tracearr documentation recommends Docker for most installs, but a source install is useful when you want to understand the moving pieces, run it alongside other native services, and build a clear recovery plan.
Rights, lawful use, and scope: This guide is for private monitoring and administration of media servers that host media you own or are authorized to use. It is not legal advice and it is not a guide to acquiring, sharing, or processing copyrighted works without permission.
Privacy warning: Tracearr-style analytics can expose usernames, IP addresses, locations, devices, watch history, timestamps, and household behavior. Treat the dashboard, logs, exports, screenshots, and backups as private data.
Where Tracearr Fits
Tracearr sits after playback begins. It does not replace Plex, Jellyfin, Emby, Sonarr, Radarr, Prowlarr, SABnzbd, or Tdarr. It watches media server sessions and turns them into live status, history, playback analytics, rules, alerts, and operator evidence.
Click each step to see how Tracearr turns media server activity into useful operational evidence.
Tracearr vs Tautulli vs General Monitoring
| Question | Tautulli Style | Tracearr Style | General Monitoring |
|---|---|---|---|
| Who is watching Plex? | Strong Plex watch history and notifications. | Also watches Plex and can include Jellyfin/Emby in one dashboard. | Usually does not understand media sessions. |
| Can I see direct play vs transcode? | Yes for Plex. | Yes as playback analytics across supported media servers. | Only indirectly through CPU/GPU metrics. |
| Can I import old history? | It is the old history source for Plex. | Can import from Tautulli or Jellystat depending on server type and support. | No media history import. |
| Can I detect account-sharing patterns? | Limited or custom. | Rules can flag concurrent streams, impossible travel, geo restrictions, and other patterns. | Not media-user aware. |
| Can I tune Tdarr/Plex from it? | Some signal from Plex behavior. | Good signal for direct-play ratio, transcode hotspots, devices, bandwidth, and user patterns. | Good host signal, but not user/session context. |
Who This Is For
- A Plex, Jellyfin, or Emby operator who wants one playback-monitoring dashboard.
- A homelab owner replacing or supplementing Tautulli with broader analytics and account rules.
- Someone tuning Plex transcodes, Tdarr output decisions, remote-user guidance, and GPU headroom from evidence.
- An operator who wants source install details instead of a black-box container only.
- A privacy-conscious admin who will protect watch history and user data.
Before You Start: Safe Defaults
| Decision | Recommended Starting Point | Why It Matters |
|---|---|---|
| Access | LAN or VPN only | Tracearr contains private session and account behavior. |
| Rules | Alert-only first | Do not terminate streams or punish users until signals are validated. |
| Claim code | Use a temporary random claim code | Initial setup should not be open to anyone who reaches the port. |
| Database | PostgreSQL with TimescaleDB | Tracearr stores time-series session data. |
| Redis | Local Redis service | Tracearr uses Redis for cache and background job queues. |
| Backups | Use database dumps or Tracearr backup features | Do not copy live raw PostgreSQL files as a backup. |
| Logs | Info level unless debugging | Debug logs may contain private operational details. |
Terms You Need
| Term | Plain-English Meaning | Why It Matters |
|---|---|---|
| Session | One active playback stream. | The basic unit Tracearr observes. |
| Direct play | The client plays the file without server-side conversion. | Usually easier on Plex CPU/GPU. |
| Transcode | The server converts video or audio for the client. | Consumes CPU/GPU and can reveal client compatibility issues. |
| Bandwidth | Network throughput used by streams. | Helps spot remote pressure and ISP bottlenecks. |
| Geolocation | Approximate location inferred from IP data. | Useful context, but not perfect evidence. |
| Trust score | A risk signal based on defined behavior. | Should guide review, not replace judgment. |
| Impossible travel | A user appears in far-apart places too quickly. | Can indicate sharing, VPN use, mobile networks, or geolocation error. |
| Concurrent stream | Multiple streams by one user at the same time. | May be normal in a household or suspicious depending on your policy. |
| Redis | Fast cache and queue service. | Tracearr needs it for background work. |
| TimescaleDB | PostgreSQL extension for time-series data. | Tracearr uses it for session and analytics history. |
Ubuntu Source Install Overview
Tracearr has three core pieces: the Node application, PostgreSQL with the TimescaleDB extension, and Redis. The official Tracearr documentation states that Docker is the recommended setup and that Tracearr requires TimescaleDB and Redis. The environment reference lists DATABASE_URL and REDIS_URL as required variables, with optional values such as PORT, NODE_ENV, LOG_LEVEL, CLAIM_CODE, and BACKUP_DIR.
Host binding warning: The example below binds Tracearr to 127.0.0.1 for safety. If you change HOST to 0.0.0.0, the app listens on all interfaces. Only do that when firewall, VPN, or reverse-proxy controls are already in place.
Preflight the Ubuntu Host
lsb_release -a
uname -a
df -h /
ss -ltnp | grep -E ':3000|:5432|:6379' || true
systemctl is-active postgresql redis-server || true
Do this before changing packages. If PostgreSQL or Redis already exists, document versions and existing use. Tracearr can coexist, but database changes such as TimescaleDB preload settings should be made deliberately.
Install Node.js, PostgreSQL, TimescaleDB, Redis, and Build Tools
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key
| sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_REPO="deb [signed-by=/etc/apt/keyrings/nodesource.gpg]"
NODE_REPO="$NODE_REPO https://deb.nodesource.com/node_22.x nodistro main"
printf '%sn' "$NODE_REPO"
| sudo tee /etc/apt/sources.list.d/nodesource.list >/dev/null
sudo install -d -m 0755 /usr/share/postgresql-common/pgdg
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc
| sudo tee /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc >/dev/null
printf '%sn'
"deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc]"
"https://apt.postgresql.org/pub/repos/apt jammy-pgdg main"
| paste -sd' ' -
| sudo tee /etc/apt/sources.list.d/pgdg.list >/dev/null
curl -fsSL https://packagecloud.io/install/repositories/timescale/timescaledb/script.deb.sh
| sudo bash
sudo apt-get update
sudo apt-get install -y
ca-certificates
curl
git
build-essential
python3
pkg-config
openssl
nodejs
postgresql-16
postgresql-client-16
postgresql-contrib-16
timescaledb-2-postgresql-16
redis-server
corepack enable
corepack prepare pnpm@10 --activate
sudo systemctl enable --now postgresql redis-server
node -v
pnpm -v
psql --version
redis-cli ping
Ubuntu codename note: The PGDG example above uses Jammy because many Ubuntu 22.04 media servers are Jammy-based. If you run Ubuntu 24.04 or newer, use the matching PostgreSQL repository line for your release instead of copying blindly.
Enable TimescaleDB Safely
sudo -u postgres psql -v ON_ERROR_STOP=1
-c "SHOW shared_preload_libraries;"
sudo -u postgres psql -v ON_ERROR_STOP=1
-c "ALTER SYSTEM SET shared_preload_libraries = 'timescaledb';"
sudo systemctl restart postgresql
sudo -u postgres psql -v ON_ERROR_STOP=1
-c "SHOW shared_preload_libraries;"
If your PostgreSQL instance already has values in shared_preload_libraries, merge them instead of replacing them. The simple command above is for a host where TimescaleDB is the only preload requirement.
Create the Tracearr User, Database, and Extension
sudo useradd --system
--home-dir /opt/tracearr
--shell /usr/sbin/nologin
tracearr 2>/dev/null || true
sudo install -d -m 0750 -o tracearr -g tracearr /var/lib/tracearr
sudo install -d -m 0750 -o tracearr -g tracearr /var/lib/tracearr/backup
sudo install -d -m 0750 -o root -g root /etc/tracearr
TRACEARR_DB_PASSWORD="REPLACE_WITH_LONG_RANDOM_PASSWORD"
sudo -u postgres psql -v ON_ERROR_STOP=1 <<SQL
DO $$
BEGIN
IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'tracearr') THEN
CREATE ROLE tracearr LOGIN PASSWORD '${TRACEARR_DB_PASSWORD}';
ELSE
ALTER ROLE tracearr WITH LOGIN PASSWORD '${TRACEARR_DB_PASSWORD}';
END IF;
END
$$;
SQL
sudo -u postgres createdb -O tracearr tracearr 2>/dev/null || true
sudo -u postgres psql -d tracearr -v ON_ERROR_STOP=1
-c "CREATE EXTENSION IF NOT EXISTS timescaledb;"
Use a real password generator in production. Do not use the placeholder in the article. Store the database URL in an env file with restricted permissions, not in public shell history, screenshots, GitHub issues, or shared notes.
Create the Tracearr Environment File
sudo tee /etc/tracearr/tracearr.env >/dev/null <<'EOF'
DATABASE_URL=postgres://tracearr:REPLACE_WITH_DB_PASSWORD@localhost:5432/tracearr
REDIS_URL=redis://localhost:6379
PORT=3000
HOST=127.0.0.1
NODE_ENV=production
LOG_LEVEL=info
JWT_SECRET=REPLACE_WITH_64_HEX_CHARS
COOKIE_SECRET=REPLACE_WITH_DIFFERENT_64_HEX_CHARS
CLAIM_CODE=REPLACE_WITH_TEMPORARY_CLAIM_CODE
BACKUP_DIR=/var/lib/tracearr/backup
APP_VERSION=REPLACE_AFTER_BUILD
APP_TAG=REPLACE_AFTER_BUILD
APP_COMMIT=REPLACE_AFTER_BUILD
APP_BUILD_DATE=REPLACE_AFTER_BUILD
EOF
sudo chown root:tracearr /etc/tracearr/tracearr.env
sudo chmod 0640 /etc/tracearr/tracearr.env
Generate JWT_SECRET and COOKIE_SECRET separately. The official Docker install guide emphasizes treating these values like passwords and rotating them if exposed. A Tracearr claim code is also a bootstrap secret. Use a placeholder in public examples and rotate it if it appears in a screenshot or log.
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 16
Clone, Pin, Install, and Build Tracearr
sudo rm -rf /opt/tracearr
sudo git clone https://github.com/connorgallopo/Tracearr.git /opt/tracearr
sudo chown -R tracearr:tracearr /opt/tracearr
cd /opt/tracearr
sudo -u tracearr git fetch --all --tags --prune
TRACEARR_TAG="$(sudo -u tracearr git tag -l 'v*'
| grep -Ev '(beta|alpha|rc)'
| sort -V
| tail -n1)"
echo "Selected Tracearr tag: ${TRACEARR_TAG}"
sudo -u tracearr git checkout "${TRACEARR_TAG}"
sudo -u tracearr HUSKY=0 CYPRESS_INSTALL_BINARY=0 pnpm install --frozen-lockfile
sudo -u tracearr pnpm turbo run build
--filter=@tracearr/shared
--filter=@tracearr/server
--filter=@tracearr/web
TRACEARR_COMMIT="$(sudo -u tracearr git rev-parse --short=12 HEAD)"
TRACEARR_BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
Do not hide the selected tag from the operator. Print it, record it, and keep it in your restore notes. A source install is manageable only when you know exactly what commit and tag were built.
Record Build Metadata
sudo sed -i
-e "s/^APP_VERSION=.*/APP_VERSION=${TRACEARR_TAG#v}/"
-e "s/^APP_TAG=.*/APP_TAG=${TRACEARR_TAG}/"
-e "s/^APP_COMMIT=.*/APP_COMMIT=${TRACEARR_COMMIT}/"
-e "s/^APP_BUILD_DATE=.*/APP_BUILD_DATE=${TRACEARR_BUILD_DATE}/"
/etc/tracearr/tracearr.env
sudo cp /etc/tracearr/tracearr.env /opt/tracearr/.env
sudo chown root:tracearr /opt/tracearr/.env
sudo chmod 0640 /opt/tracearr/.env
If the UI ever shows version 0.0.0, missing or incorrect build metadata is one of the first things to check. Keep APP_VERSION, APP_TAG, APP_COMMIT, and APP_BUILD_DATE accurate after upgrades.
Create the systemd Service
sudo tee /etc/systemd/system/tracearr.service >/dev/null <<'EOF'
[Unit]
Description=Tracearr Service
Wants=network-online.target postgresql.service redis-server.service
After=network-online.target postgresql.service redis-server.service
[Service]
User=tracearr
Group=tracearr
EnvironmentFile=/etc/tracearr/tracearr.env
Environment=NODE_ENV=production
Type=exec
Restart=on-failure
RestartSec=10
WorkingDirectory=/opt/tracearr
ExecStart=/usr/bin/node /opt/tracearr/apps/server/dist/index.js
UMask=0027
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now tracearr
Verify Tracearr Starts Cleanly
systemctl status tracearr --no-pager
journalctl -u tracearr -n 100 --no-pager
curl -fsS http://127.0.0.1:3000/health
sudo -u postgres psql -d tracearr -c "dx timescaledb"
redis-cli ping
Success means the service is active, the health endpoint responds, PostgreSQL can see the TimescaleDB extension in the Tracearr database, Redis responds with PONG, and logs do not show database, Redis, migration, or permission errors.
First-Run Setup
- Open Tracearr through LAN, VPN, localhost tunnel, or reverse proxy.
- Use the claim code from the private env file only during first setup.
- Create the first admin account.
- Connect Plex, Jellyfin, or Emby.
- Start one known local playback session.
- Confirm Tracearr shows the active session.
- Verify direct play vs transcode status, user, device, and bandwidth data.
- Stop the stream and confirm the session lands in history.
- Remove, rotate, or restrict the claim code after setup if it is no longer needed.
Import Tautulli History Carefully
If you are replacing Tautulli, keep Tautulli available until import and validation are complete. Importing history is not the same as replacing every notification, script, statistic, or habit your household expects.
- Back up Tautulli first.
- Record the Tautulli version and service path.
- Export or document the API key privately.
- Connect the Plex server in Tracearr before importing history.
- Run the import from the Tracearr UI or supported import workflow.
- Compare high-level counts: users, history range, recent sessions, and skipped records.
- Leave Tautulli stopped-but-restorable until you trust Tracearr operations.
sudo systemctl status snap.tautulli.tautulli.service --no-pager || true
sudo systemctl cat snap.tautulli.tautulli.service || true
sudo install -d -m 0750 /opt/app-backups/tautulli-pre-tracearr
sudo tar -C / -czf
/opt/app-backups/tautulli-pre-tracearr/tautulli-data.tgz
root/snap/tautulli/common/Tautulli 2>/dev/null || true
Rules: Start Alert-Only
Tracearr rules are powerful because they can evaluate session behavior and take action. The correct first posture is alert-only. Notify the admin, review the evidence, and only later decide whether any rule should terminate streams or message users automatically.
| Rule Area | Good First Use | Risk to Avoid |
|---|---|---|
| Concurrent streams | Notify when a user exceeds your expected stream count. | Terminating normal household usage before policy is clear. |
| Impossible travel | Flag sessions that appear geographically impossible. | Assuming geolocation is perfect or ignoring VPN/mobile network behavior. |
| Geo restrictions | Notify on unexpected countries or regions. | Blocking travel, VPN, or inaccurate IP data too aggressively. |
| Heavy transcoding | Notify when a user or client repeatedly transcodes large streams. | Punishing users for a client setting you can help them fix. |
| Inactive accounts | Review dormant users before pruning access. | Deleting access without a retention and communication policy. |
Rules should move from observation to decision only after you trust the signal.
Use Tracearr to Improve Plex and Tdarr
Tracearr becomes especially useful when you connect playback evidence to your Tdarr and Plex decisions. If most users direct play, your Tdarr profile and client guidance are probably working. If one client transcodes everything, the fix might be a client setting, subtitle behavior, audio compatibility, or network limitation rather than another GPU.
| Tracearr Signal | Possible Meaning | Operational Response |
|---|---|---|
| High transcode ratio | Clients cannot direct play the files you store. | Review client support, subtitles, audio, bitrate, and Tdarr output policy. |
| Many remote high-bitrate streams | Remote bandwidth pressure is real. | Use Plex remote quality guidance, better encodes, or network capacity planning. |
| One user transcodes everything | Client setting or device limitation. | Help that user change quality settings or choose a better client. |
| Peak playback overlaps Tdarr jobs | Batch work may compete with user playback. | Lower Tdarr workers during viewing hours. |
| Low engagement with a library | Content is stale or request policy is noisy. | Audit Seerr/List intake and cleanup policies. |
| Suspicious multi-location sessions | Possible sharing, VPN, travel, or bad geolocation. | Review before action; do not assume guilt from one signal. |
Backups
Tracearr data is database-backed and privacy-sensitive. Do not copy live PostgreSQL data directories as your backup strategy. Use Tracearr backup features when available, or use pg_dump for a consistent database backup. Store env files and dumps on restricted storage, ideally backed by NAS snapshots or off-host backups.
sudo install -d -m 0750 /var/backups/tracearr
sudo -u postgres pg_dump -Fc tracearr
| sudo tee /var/backups/tracearr/tracearr-db.dump >/dev/null
sudo tar -C / -czf /var/backups/tracearr/tracearr-config.tgz
etc/tracearr
etc/systemd/system/tracearr.service
sudo tar -C /opt -czf /var/backups/tracearr/tracearr-source-notes.tgz
tracearr/.git/HEAD
tracearr/.git/refs 2>/dev/null || true
Those backups may include secrets, tokens, claim codes, user history, private hostnames, and viewing behavior. Do not post them publicly. Do not attach real env files to public support requests.
Upgrade Routine
- Back up the database with
pg_dumpor the built-in backup workflow. - Back up
/etc/tracearrand record the current app tag and commit. - Stop Tracearr.
- Fetch tags and choose a stable target tag.
- Install dependencies and build.
- Update app metadata in the env file.
- Start Tracearr and watch migrations/logs.
- Verify health, UI version, active sessions, server connection, and recent history.
sudo systemctl stop tracearr
cd /opt/tracearr
sudo -u tracearr git fetch --all --tags --prune
TRACEARR_TAG="$(sudo -u tracearr git tag -l 'v*'
| grep -Ev '(beta|alpha|rc)'
| sort -V
| tail -n1)"
echo "Target Tracearr tag: ${TRACEARR_TAG}"
sudo -u tracearr git checkout "${TRACEARR_TAG}"
sudo -u tracearr HUSKY=0 CYPRESS_INSTALL_BINARY=0 pnpm install --frozen-lockfile
sudo -u tracearr pnpm turbo run build
--filter=@tracearr/shared
--filter=@tracearr/server
--filter=@tracearr/web
sudo systemctl start tracearr
curl -fsS http://127.0.0.1:3000/health
journalctl -u tracearr -n 100 --no-pager
Rollback Routine
If an upgrade fails before database migrations, a code rollback may be enough. If migrations ran, restore the pre-upgrade database dump before running older code. Keep the previous tag, commit, env file, and database dump together.
sudo systemctl stop tracearr
cd /opt/tracearr
sudo -u tracearr git checkout PREVIOUS_KNOWN_GOOD_TAG
sudo -u tracearr pnpm install --frozen-lockfile
sudo -u tracearr pnpm turbo run build
--filter=@tracearr/shared
--filter=@tracearr/server
--filter=@tracearr/web
# If a migration ran, restore the pre-upgrade database dump here.
sudo systemctl start tracearr
curl -fsS http://127.0.0.1:3000/health
Docker Option for Readers Who Want the Recommended Path
The upstream recommended Tracearr deployment is Docker Compose with Tracearr, TimescaleDB, and Redis. If you use Docker, prefer the official compose example and use database-aware backups. Do not treat raw PostgreSQL data directory copies as a safe backup while the database is running.
# Official quick-start pattern from the Tracearr docs:
TRACEARR_COMPOSE_URL="https://raw.githubusercontent.com/connorgallopo/Tracearr/main"
curl -L -o docker-compose.pg18.yml
"$TRACEARR_COMPOSE_URL/docker/examples/docker-compose.pg18.yml"
echo "JWT_SECRET=$(openssl rand -hex 32)" > .env
echo "COOKIE_SECRET=$(openssl rand -hex 32)" >> .env
docker compose -f docker-compose.pg18.yml up -d
Troubleshooting
| Symptom | Likely Cause | What to Check |
|---|---|---|
| Tracearr will not start | Missing env variables, build failure, DB issue, or Redis issue. | journalctl -u tracearr, DATABASE_URL, REDIS_URL, and build output. |
| Version shows 0.0.0 | Missing app metadata. | Check APP_VERSION, APP_TAG, APP_COMMIT, and APP_BUILD_DATE. |
| Health endpoint fails | Server process is not listening or cannot complete startup. | Check service status, port 3000, DB connection, and Redis connection. |
| Cannot connect Plex/Jellyfin/Emby | Wrong URL/API/token, TLS mismatch, or network isolation. | Test the media server URL from the Tracearr host. |
| No active sessions appear | Integration incomplete or no playback is active. | Start one known stream and watch logs. |
| Geolocation looks wrong | IP geolocation is approximate or VPN/mobile routing is involved. | Treat location as context and review more evidence. |
| Pages feel slow | Database/Redis issue, large import, or constrained host. | Check Postgres health, Redis, disk I/O, and server load. |
| Import skips records | Old history does not map cleanly or server/users differ. | Review import logs and compare high-level counts, not every row blindly. |
FAQ
Does Tracearr replace Tautulli?
It can replace or supplement Tautulli depending on your needs. Treat it as a migration project, not a magic drop-in. Validate history import, active sessions, notifications, user data, and daily workflows before retiring Tautulli.
Should Tracearr be exposed to the internet?
Usually no. Tracearr is an admin and analytics dashboard. LAN, VPN, or tightly controlled reverse-proxy access is the safer default.
Should account-sharing rules terminate streams automatically?
Not at first. Start alert-only, validate geolocation and user behavior, then decide whether any automatic action is appropriate.
Can Tracearr help reduce transcoding?
Yes. It can show direct play vs transcode patterns, problematic clients, high-bandwidth sessions, and peak-time pressure. Use that evidence to tune Plex, client guidance, Tdarr output, and worker schedules.
Series Navigation
Tracearr is part of the TechGeeks Plex, Arr, and Tdarr homelab series. These companion articles fill in the surrounding architecture, security, storage, monitoring, and automation decisions.
- Complete beginner setup
- Plex architecture
- Sonarr setup
- Radarr setup
- Prowlarr setup
- Radarr import lists
- Custom formats
- GPU strategy
- Reverse proxy security
- Backups and disaster recovery
- Monitoring and health checks
- Series hub
References
- Tracearr documentation
- Tracearr Docker Compose installation guide
- Tracearr environment variables
- Tracearr rules documentation
- Tracearr FAQ
- TechGeeks monitoring and health checks guide
- TechGeeks Plex and Tdarr GPU strategy
- TechGeeks reverse proxy guide
- TechGeeks backup guide
Need help applying this?
Bring TechGeeks into the real environment.
If you are working through this on a live network, WordPress site, Linux server, AI workflow, or PisoWiFi deployment, send the context and we can help turn it into a practical plan.

