Why Logarr?

Running a media server stack means juggling multiple dashboards, each with their own logs and error reporting. When something breaks, you're chasing cascading failures across apps while the goalposts keep moving.

Logarr aggregates logs from all your servers, automatically detects and ranks issues by impact, and helps you track them to resolution—all from a single dashboard.

Screenshots

Features

Supported Servers

Logarr uses a provider architecture—adding support for new servers is straightforward. Contributions welcome!

Quick Start

Using Pre-built Images (Quickest)

Logarr publishes pre-built Docker images to both GitHub Container Registry and Docker Hub:

# Create docker-compose.yml with:
services:
  backend:
    image: itz4blitz/logarr-backend:latest
    # ... rest of configuration
  frontend:
    image: itz4blitz/logarr-frontend:latest
    # ... rest of configuration

See the full docker-compose.yml for complete configuration.

Docker Compose (Recommended)

git clone https://github.com/itz4blitz/logarr.git
cd logarr
cp .env.example .env
docker compose up -d

Open http://localhost:3001 and add your first server.

Development

pnpm install
pnpm docker:dev      # Start PostgreSQL & Redis
pnpm db:push         # Initialize database
pnpm dev             # Start dev servers

• Frontend: http://localhost:3001
• API: http://localhost:4001/api
• Docs: http://localhost:4001/api/docs

Architecture

flowchart TB
    subgraph Client
        FE[Next.js Frontend]
    end

    subgraph Backend
        API[NestJS API]
        WS[WebSocket Server]
    end

    subgraph Data
        PG[(PostgreSQL)]
        RD[(Redis)]
    end

    subgraph Providers
        PX[Plex]
        JF[Jellyfin]
        EM[Emby]
        SO[Sonarr]
        RA[Radarr]
        PR[Prowlarr]
        WH[Whisparr]
    end

    FE <--> API
    FE <--> WS
    API <--> PG
    API <--> RD
    API <--> PX & JF & EM & SO & RA & PR & WH

How It Works

Log Ingestion — Providers connect via WebSocket or polling (configurable per server). Logs are deduplicated using external activity IDs.

Error Fingerprinting — Similar errors are normalized and hashed to group thousands of occurrences into single trackable issues.

Impact Scoring — Each issue receives a 0-100 score based on severity (40%), frequency (25%), affected users (20%), sessions (10%), and recency (5%).

Configuration

Environment Variables

# Required
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/logarr
REDIS_URL=redis://localhost:6380

# Optional - AI Analysis (auto-configured on startup if set)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_AI_API_KEY=...

# Optional - Local AI
OLLAMA_BASE_URL=http://localhost:11434
LMSTUDIO_BASE_URL=http://localhost:1234/v1

# Optional - Media Servers (auto-configured on startup if set)
JELLYFIN_URL=http://jellyfin:8096
JELLYFIN_API_KEY=...
PLEX_URL=http://plex:32400
PLEX_TOKEN=...

# Optional - Data Retention (defaults shown)
LOG_RETENTION_DAYS=30           # Days to keep info/debug logs
LOG_RETENTION_ERROR_DAYS=90     # Days to keep error/warn logs
LOG_CLEANUP_ENABLED=true        # Enable automatic cleanup
LOG_CLEANUP_CRON=0 3 * * *      # Cleanup schedule (default: 3 AM daily)

Data Retention

Logarr automatically cleans up old logs to prevent unbounded database growth—essential for home servers with limited storage.

Configuration options:

• Environment variables — Set defaults in docker-compose.yml or .env
• Settings UI — Adjust at runtime via Settings → Data Management

Issues and statistics are preserved even after logs are deleted. The Data Management page shows storage usage, cleanup history, and lets you preview or trigger manual cleanup.

Adding Servers

1. Navigate to Sources → Add Source
2. Select server type and enter URL + API key
3. Test connection and save

Alternatively, set environment variables (e.g., JELLYFIN_URL and JELLYFIN_API_KEY) and servers will be auto-configured on startup.

File-Based Log Ingestion

For deeper log analysis, Logarr can read log files directly from your media servers. This captures detailed application logs that APIs don't expose.

Setup (Docker)

1. Set log paths in .env — Point to your host machine's log directories:

# Media Servers
PLEX_LOGS_PATH=/path/to/plex/Library/Application Support/Plex Media Server/Logs
JELLYFIN_LOGS_PATH=/path/to/jellyfin/config/log
EMBY_LOGS_PATH=/path/to/emby/config/logs

# *arr Apps
SONARR_LOGS_PATH=/path/to/sonarr/config/logs
RADARR_LOGS_PATH=/path/to/radarr/config/logs
PROWLARR_LOGS_PATH=/path/to/prowlarr/config/logs
WHISPARR_LOGS_PATH=/path/to/whisparr/config/logs

2. Restart Logarr — The docker-compose mounts these paths automatically.

3. Configure in UI — Go to Sources → Edit your server → Enable file ingestion with the container path:

Multiple Instances (e.g., Movies vs Shorts, 1080p vs 4K)

To run multiple instances of the same server type, use numbered environment variables:

# Primary Radarr instance (for Movies)
RADARR_URL=http://radarr-movies:7878
RADARR_API_KEY=your_api_key
RADARR_LOGS_PATH=/path/to/radarr-movies/logs

# Secondary Radarr instance (for Shorts)
RADARR_LOGS_PATH_1=/path/to/radarr-shorts/logs
RADARR_LOGS_PATH_2=/path/to/radarr-4k/logs

The numbered instances are mounted as:

• /radarr-logs-1
• /radarr-logs-2
• /radarr-logs-3

Simply add multiple servers in the UI using the same server type but different URLs and log paths.

Note: You can have up to 3 additional instances per server type beyond the primary. Add each instance as a separate server in the Sources UI.

Common Log Locations

API Reference

Once running, Swagger docs are available at http://localhost:4001/api/docs.

WebSocket Events

// Connect to ws://localhost:4001/logs
socket.on('log', (log) => {}); // New log entry
socket.on('issue.created', (issue) => {}); // New issue detected
socket.on('session.started', (session) => {}); // Playback started

Project Structure

logarr/
├── apps/
│   ├── backend/            # NestJS API
│   └── frontend/           # Next.js app
├── packages/
│   ├── core/               # Shared types and utilities
│   ├── provider-plex/      # Plex integration
│   ├── provider-jellyfin/  # Jellyfin integration
│   ├── provider-emby/      # Emby integration
│   ├── provider-sonarr/    # Sonarr integration
│   ├── provider-radarr/    # Radarr integration
│   ├── provider-prowlarr/  # Prowlarr integration
│   ├── provider-whisparr/  # Whisparr integration
│   └── provider-arr/       # Base *arr provider
└── docker-compose.yml

Upgrading

Logarr uses pre-built Docker images by default, making upgrades simple:

Automatic Upgrade Script

Linux/Mac:

chmod +x update.sh
./update.sh

Windows (PowerShell):

.\update.ps1

Manual Upgrade

docker compose down
docker compose pull
docker compose up -d

Pinning to a Specific Version

By default, Logarr uses the :latest tag. To pin to a specific version (recommended for production):

# In your .env file or docker-compose.yml
LOGARR_VERSION=0.5.5

Or set it per-run:

LOGARR_VERSION=0.5.5 docker compose up -d

Building from Source

If you prefer to build from source instead of using pre-built images:

# Set environment variable to enable local builds
LOGARR_BUILD_LOCALLY=1

# Or build manually
docker compose build --no-cache
docker compose up -d

Image Registries

Logarr images are published to:

• GitHub Container Registry: ghcr.io/itz4blitz/logarr-backend and ghcr.io/itz4blitz/logarr-frontend
• Docker Hub: itz4blitz/logarr-backend and itz4blitz/logarr-frontend

To use Docker Hub instead of GHCR:

LOGARR_IMAGE_REGISTRY=docker.io/itz4blitz

Contributing

git checkout -b feature/your-feature
# Make changes
git commit -m 'Add your feature'
git push origin feature/your-feature
# Open a Pull Request

Guidelines: TypeScript strict mode, ESLint + Prettier, tests for new features.

Testing

Logarr has comprehensive test coverage using Vitest.

Running Tests

pnpm test              # Run all tests
pnpm test:coverage     # Run with coverage report
pnpm test:e2e          # Run Playwright E2E tests

Test Packages

Coverage thresholds are enforced at 80% for statements, branches, functions, and lines.

Roadmap

This project is under active development. Check out our GitHub Discussions for feature requests, ideas, and community conversations.

License

MIT — see LICENSE for details.