marcinlis82/pigeon-pod repository overview

⁠PigeonPod

PigeonPod is a self-hosted podcast aggregation and subscription platform that automatically turns YouTube channels and playlists into standard, subscribable podcast feeds.

⁠🌟 Key Features

• Multi-User Management & RBAC: Role-based access control with discrete Admin and standard User accounts, isolated feeds, and dedicated account management.
• Extended Usage & Download Statistics: Interactive analytics dashboard with KPI overview cards, per-podcast and per-user drilldowns, search, multi-column sorting, and filtering.
• Enterprise Security Hardening:
  • Administrative role checks on sensitive endpoints (notifications, platform cookies).
  • Built-in SSRF protection blocking intranet/loopback/cloud metadata IP ranges on outbound webhooks.
  • Adaptive BCrypt password hashing with constant-time verification.
  • DOMPurify HTML sanitization for public podcast episode descriptions.
• Automated Sync & Background Downloads: Automatically monitors feeds and downloads new episodes in audio or video formats using yt-dlp and FFmpeg.
• Granular Download Policies: Filter episodes by title/description keywords, min/max duration, or exclude YouTube Live streams and Premieres.
• Podcast 2.0 Ready: Standard RSS / iTunes / Podcasting 2.0 XML feeds with transcript, subtitle, and chapter support.
• Built-in Global Web Player: Listen to audio or watch video episodes directly inside the modern web interface.

⁠🚀 Quick Start

⁠1. Docker Run

Run PigeonPod with a persistent SQLite database volume:

docker run -d \
  --name pigeon-pod \
  -p 8834:8080 \
  -v pigeon-pod-data:/data \
  -e SPRING_DATASOURCE_URL=jdbc:sqlite:/data/pigeon-pod.db \
  -e PIGEON_LOG_FILE=/data/logs/pigeon-pod.log \
  --restart unless-stopped \
  marcinlis82/pigeon-pod:1.0.4

⁠2. Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'

services:
  pigeon-pod:
    image: marcinlis82/pigeon-pod:1.0.4
    container_name: pigeon-pod
    restart: unless-stopped
    ports:
      - '8834:8080'
    environment:
      - SPRING_DATASOURCE_URL=jdbc:sqlite:/data/pigeon-pod.db
      - PIGEON_LOG_FILE=/data/logs/pigeon-pod.log
    volumes:
      - pigeon-pod-data:/data

volumes:
  pigeon-pod-data:

Start the container:

docker compose up -d

⁠3. Accessing the Web Interface

Open your browser and navigate to:

http://localhost:8834

On initial startup, log in with the administrator account to configure system settings, add feeds, and invite users.

⁠⚙️ Environment Variables

⁠📁 Persistent Data Paths

Mount the container /data directory to preserve your data across updates:

• /data/pigeon-pod.db: SQLite database file.
• /data/media/: Downloaded audio and video episodes.
• /data/covers/: Podcast feed and episode cover artwork.
• /data/logs/: Application execution logs.

⁠📄 License

PigeonPod is licensed under the GNU General Public License v3.0 (GPLv3).