# Tautulli

> Monitoring and tracking for Plex Media Server.

- Category: Media & Entertainment
- Difficulty: beginner
- Components: tautulli
- Tags: tautulli, plex, monitoring, statistics
- Source: https://docker.recipes/media/tautulli

## Overview

Tautulli is a comprehensive monitoring and analytics platform specifically designed for Plex Media Server environments. Originally forked from PlexPy in 2017, Tautulli has evolved into the de facto standard for tracking Plex usage patterns, user behavior, and server performance metrics. The application provides detailed insights into who's watching what, when they're watching it, and how your media server is performing under load. This Docker stack deploys Tautulli using the LinuxServer.io image, which includes automatic security updates and proper permission handling for containerized environments. The configuration exposes Tautulli's web interface on port 8181 and maintains persistent storage for historical data, user configurations, and database records. Tautulli connects directly to your Plex Media Server via API calls to gather real-time streaming data and historical usage statistics. Media server administrators, Plex enthusiasts, and home lab operators will find this stack invaluable for understanding their media consumption patterns and optimizing server performance. The combination provides enterprise-grade monitoring capabilities for personal and shared Plex installations, enabling data-driven decisions about content curation, bandwidth management, and user experience improvements.

## Features

- Real-time stream monitoring with detailed transcoding information and bandwidth usage
- Historical playback statistics with user activity timelines and content popularity metrics
- Comprehensive user management with individual viewing histories and device tracking
- Advanced notification system supporting Discord, Slack, Pushover, and custom webhooks
- Automated newsletter generation featuring recently added content and viewing summaries
- Geographic tracking and IP address monitoring for stream location awareness
- Library growth analytics with content addition trends and storage utilization
- Custom dashboard creation with personalized widgets and statistical visualizations

## Use cases

- Home media server operators tracking family viewing habits and optimizing content libraries
- Shared Plex server administrators monitoring user activity and managing bandwidth consumption
- Media enthusiasts analyzing their personal viewing patterns and discovering content trends
- IT professionals maintaining corporate media servers with detailed usage reporting requirements
- Content curators using viewing statistics to make informed decisions about library expansion
- Network administrators monitoring Plex server performance and identifying transcoding bottlenecks
- Multi-user households tracking individual device usage and setting up parental monitoring

## Prerequisites

- Running Plex Media Server instance with administrative access and valid authentication token
- Minimum 512MB RAM allocation for Tautulli container and database operations
- Network connectivity between Tautulli container and Plex Media Server on port 32400
- Available port 8181 on Docker host for web interface access and initial configuration
- Persistent storage capacity for historical data retention (minimum 1GB recommended)
- Basic understanding of Plex server architecture and user management concepts

## docker-compose.yml

```yaml
services:
  tautulli:
    image: linuxserver/tautulli:latest
    container_name: tautulli
    restart: unless-stopped
    environment:
      PUID: 1000
      PGID: 1000
      TZ: UTC
    volumes:
      - tautulli_config:/config
    ports:
      - "8181:8181"

volumes:
  tautulli_config:
```

## .env

```bash
# No additional config needed
```

## Usage notes

- Docs: https://github.com/Tautulli/Tautulli/wiki
- Access at http://localhost:8181 - setup wizard on first run
- Connect to Plex: Settings > Plex Media Server (use Plex token)
- View history, statistics, and currently watching
- Notifications: Discord, email, Pushover when users stream
- Newsletter feature for recently added content summaries

## Troubleshooting

- Database is locked errors: Stop Tautulli container, check for corrupted database files in config volume, restore from backup if necessary
- Plex connection timeout issues: Verify Plex token validity in Tautulli settings, ensure network connectivity, and check firewall rules between containers
- Missing historical data after container restart: Confirm config volume persistence, check database file permissions, and verify PUID/PGID settings match host filesystem
- Web interface loading blank pages: Clear browser cache, check container logs for JavaScript errors, and verify timezone environment variable format
- Notification delivery failures: Test notification agents individually, verify webhook URLs and authentication tokens, check network connectivity to external services
- High memory usage and performance issues: Increase database cleanup frequency, reduce notification history retention, and consider upgrading container memory limits

