Quick Start • Features • Docker Hub • Screenshots

---

🚀 What is Ghostarr?

Ghostarr automatically collects statistics and content from your media server services (Tautulli, Komga, Audiobookshelf, ROMM, Tunarr) and generates beautiful, responsive newsletters published to Ghost CMS. Keep your users informed about what's trending, new additions, and viewing statistics - all automated!

Perfect for:

• 🏠 Homelab owners sharing media with family & friends
• 📊 Media server admins wanting automated reports
• 📧 Ghost blog owners with media content
• 🤖 Anyone who wants set-it-and-forget-it newsletters

Warning

Vibe Coded Project - This application was built 100% using AI-assisted development with Claude Code.

---

✨ Features

🎬 Multi-Source Integration 7 homelab services Tautulli - Plex statistics Ghost - Newsletter publishing TMDB - Metadata enrichment ROMM - Game library Komga - Comics & manga Audiobookshelf - Audiobooks Tunarr - TV programming

📅 Smart Scheduling Fully automated CRON-based scheduling Timezone support Manual generation Real-time progress Scheduled cleanup Retention policies

📊 Rich Content Beautiful newsletters Ranking evolution Play statistics New additions Maintenance notices Custom templates Preview before send

🎨 Modern Web UI

• 🌐 5 languages (EN, FR, DE, ES, IT)
• 🌓 Light/Dark/Auto themes
• 📱 Fully responsive design
• 💾 Export/Import configuration
• 📈 Complete history tracking

📬 Flexible Publishing

• Draft only - Review before publishing
• Site only - Blog post without email
• Email only - Newsletter distribution
• Site + Email - Full publication

🔧 Maintenance Notices

Inform your users about planned maintenance or incidents:

• Scheduled maintenance - Planned downtime
• Outage / Network issue - Incident communication
• Update / Improvement - New features announcement
• Security - Security-related notices

---

🏃 Quick Start

Docker Compose (Recommended)

services:
  ghostarr:
    image: sharkhunterr/ghostarr:latest
    container_name: ghostarr
    ports:
      - "8080:8080"
    volumes:
      - ./config:/config
    environment:
      - TZ=Europe/Paris
      - APP_SECRET_KEY=your-secret-key-minimum-32-characters
    restart: unless-stopped

docker compose up -d

Access: http://localhost:8080

Docker Run

docker run -d \
  --name ghostarr \
  -p 8080:8080 \
  -v $(pwd)/config:/config \
  -e TZ=Europe/Paris \
  -e APP_SECRET_KEY=your-secret-key-minimum-32-characters \
  sharkhunterr/ghostarr:latest

---

🔧 Configuration

Environment Variables

Variable	Default	Description
APP_SECRET_KEY	required	Encryption key (min 32 chars)
TZ	UTC	Container timezone
APP_LOG_LEVEL	INFO	Log level (DEBUG, INFO, WARNING, ERROR)
PORT	8080	Server port

First Launch

1. Configure Services - Add your Tautulli, Ghost, and other service credentials
2. Test Connections - Validate each service is reachable
3. Create a Template - Or use the default newsletter template
4. Generate! - Create your first newsletter manually or set up a schedule

---

🎯 Service Setup

Tautulli

Fetches watch statistics, top movies, TV shows, and user activity from your Plex server.

1. Open Tautulli → Settings → Web Interface
2. Copy the API Key
3. Enter URL: http://your-tautulli:8181

Ghost

Publishes newsletters to your Ghost blog.

1. Open Ghost Admin → Settings → Integrations
2. Add a Custom Integration
3. Copy the Admin API Key
4. Enter URL: http://your-ghost:2368

TMDB (Optional)

Enriches movies and TV shows with metadata, ratings, and artwork.

1. Create account at themoviedb.org
2. Generate an API key in account settings
3. Only API key needed (no URL)

Other Services

• ROMM - Game library (URL + username/password or API key)
• Komga - Comics library (URL + API key)
• Audiobookshelf - Audiobooks (URL + API token)
• Tunarr - TV channels (URL only, no auth required)

---

🏗️ Architecture

Global Architecture

flowchart TB
    subgraph UI["🖥️ Web Interface"]
        REACT[React Frontend]
    end

    subgraph Backend["⚙️ FastAPI Backend :8080"]
        API[REST API<br/>/api/v1/*]
        SCHED[APScheduler<br/>CRON Jobs]
        GEN[Newsletter<br/>Generator]
        SSE[SSE Progress<br/>Streaming]
    end

    subgraph Data["💾 Data Layer"]
        DB[(SQLite<br/>Database)]
        TPL[Jinja2<br/>Templates]
    end

    subgraph Services["🔧 External Services"]
        TAU[Tautulli]
        GHOST[Ghost CMS]
        TMDB[TMDB]
        ROMM[ROMM]
        KOMGA[Komga]
        ABS[Audiobookshelf]
        TUN[Tunarr]
    end

    REACT -->|HTTP| API
    REACT -->|SSE| SSE

    API --> GEN
    SCHED --> GEN
    GEN --> SSE

    API --> DB
    SCHED --> DB
    GEN --> TPL

    GEN -->|Fetch Stats| TAU
    GEN -->|Fetch Metadata| TMDB
    GEN -->|Fetch Games| ROMM
    GEN -->|Fetch Comics| KOMGA
    GEN -->|Fetch Books| ABS
    GEN -->|Fetch Channels| TUN
    GEN -->|Publish| GHOST

Loading

Newsletter Generation Flow

sequenceDiagram
    participant User as 👤 User
    participant UI as 🖥️ Frontend
    participant API as ⚙️ Backend
    participant Services as 🔧 Services
    participant Ghost as 👻 Ghost

    User->>UI: Click "Generate"
    UI->>API: POST /newsletters/generate

    Note over API: Create History Entry
    API-->>UI: generation_id
    UI->>API: SSE /progress/{id}

    loop For Each Enabled Source
        API->>Services: Fetch Data
        Services-->>API: Movies, Shows, Games...
        API-->>UI: Progress Update
    end

    Note over API: Render Jinja2 Template
    API-->>UI: Progress: Rendering

    API->>Ghost: POST /ghost/api/admin/posts
    Ghost-->>API: Post Created

    Note over API: Update History
    API-->>UI: Progress: Complete
    UI-->>User: ✅ Newsletter Published!

Loading

Scheduling Flow

flowchart LR
    subgraph Triggers["⏰ Triggers"]
        CRON[CRON Schedule]
        MANUAL[Manual Execution]
    end

    subgraph Actions["📋 Actions"]
        GEN_ACT[Generate Newsletter]
        DEL_ACT[Cleanup Old Entries]
    end

    subgraph Results["📊 Results"]
        HISTORY[History Entry]
        GHOST_POST[Ghost Post]
        DELETED[Deleted Records]
    end

    CRON --> GEN_ACT
    CRON --> DEL_ACT
    MANUAL --> GEN_ACT
    MANUAL --> DEL_ACT

    GEN_ACT --> HISTORY
    GEN_ACT --> GHOST_POST
    DEL_ACT --> HISTORY
    DEL_ACT --> DELETED

Loading

---

📸 Screenshots

📊 Dashboard & Generation

Manual Generation	Schedule Management

📝 History & Templates

Generation History	Template Editor

⚙️ Settings

Services Config	General Settings

---

🌐 Multi-Language Support

Ghostarr is fully translated into 5 languages:

🇬🇧 English • 🇫🇷 Français • 🇩🇪 Deutsch • 🇪🇸 Español • 🇮🇹 Italiano

Change language anytime from Settings → General.

---

🛠️ Technology Stack

Layer	Technologies
Backend	Python 3.11 • FastAPI • SQLAlchemy • Alembic • APScheduler
Frontend	React 18 • TypeScript • Tailwind CSS • Vite • Radix UI
Data	SQLite • Zustand • React Query
DevOps	Docker • GitLab CI

---

📦 Data & Backup

Volumes

Path	Content
/config/data.db	SQLite database (settings, history, schedules)
/config/templates/	Custom newsletter templates

Export/Import

Ghostarr supports full configuration export including:

• User preferences
• Retention settings
• Service configurations (with encrypted credentials)

Go to Settings → General → Export/Import

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run linting: npm run lint
4. Submit a pull request

---

🙏 Acknowledgments

The Need: Sharing a media server with family and friends is great, but keeping everyone informed about new content, viewing stats, and what's trending was tedious — manual updates, scattered information, no unified communication.

The Solution: Ghostarr was born to automate media server newsletters. Connect your services once, set up a schedule, and let your users discover what's new without you lifting a finger.

The Approach: As a young parent with limited time and no fullstack development experience (neither backend nor frontend), traditional coding wasn't an option. Built entirely through Claude Code using "vibe coding" — pure conversation, no manual coding required.

Special thanks to the homelab community and all contributors!

---

📄 License

MIT License - see LICENSE file for details.

---

Built with Claude Code 🤖 for the homelab community 🏠

⭐ Star on GitHub • 🐛 Report Bug • 💡 Request Feature