Finalarr
Docker app from Abrechen2's Repository
Season-finale and season-complete notifier for Sonarr.
Overview
Readme
View on GitHub![]()
Finalarr
Season-finale and season-complete notifier for Sonarr. Finalarr tells you — once — when a series or anime you follow has new episodes on disk, when its season finale has landed and when the season is complete. It also tells you what you are still waiting for: renewals, announced sequels, postponed episodes and the next air date.
Status: 0.4, the first release. It runs daily against a real library; expect changes until 1.0.
What it does
- Knows how long a season is. Expected episode count from Sonarr, cross-checked with AniList for anime (split cours included). When the two disagree it says so instead of guessing; one click picks either number.
- Reports each thing exactly once: new episodes on disk (as ranges, one message per batch), the season finale, a finished split-cour part, a complete season, a season or sequel announced before Sonarr knows it, and an episode whose air date was postponed. Nothing is reported for what was already on disk when you started following.
- Shows what you are waiting for on every series page: one sentence ("Season 3 is announced; the date is still open"), the next episode with a countdown, where to watch it, the trailer (loaded only on click) and season/episode news without merchandise.
- Follows what you watch: connect Emby, Jellyfin or Plex, pick whose viewing counts, and Finalarr follows the series you actually watch — and shows who watched which episode and what is still unwatched.
- Calendar in the app and as a subscribable iCal feed — finales only, premieres and finales, or every episode.
- Channels: Telegram, Discord, Pushover, a webhook or any Apprise URL; German or English messages, event filter and quiet hours per channel.
- One Docker container, SQLite, web UI in English and German, dark and light theme.
Not for you if you want a downloader, movie support (Radarr) or Sonarr v3.
Install
Finalarr needs two keys. Generate them once and keep them:
openssl rand -hex 32 # FINALARR_API_KEY (also your login)
openssl rand -base64 32 | tr '+/' '-_' # FINALARR_SECRET_KEY (encrypts stored secrets)
Docker Compose
services:
finalarr:
image: ghcr.io/abrechen2/finalarr:latest # or a release tag such as 0.4.0
container_name: finalarr
restart: unless-stopped
ports:
- "5790:5790"
environment:
- FINALARR_API_KEY=change-me
- FINALARR_SECRET_KEY=change-me
- PUID=1000
- PGID=1000
- TZ=Europe/Berlin
# - FINALARR_AUTH=local # no login from your home network
volumes:
- ./finalarr:/config
stop_grace_period: 90s
docker compose up -d # then open http://<host>:5790 and follow the setup
Unraid
Search for Finalarr in Community Applications, or use the template in
unraid/my-finalarr.xml.
Keep it inside your home network: don't forward port 5790; for remote access use a VPN or a reverse proxy with HTTPS (see docs/DEPLOY.md).
Setup
The setup page walks you through it: add your Sonarr (URL and API key), paste the webhook URL Finalarr shows into Sonarr → Settings → Connect → Webhook, choose the series to follow and add a notification channel. All other options, optional keys (TMDB, Trakt, AnimeSchedule.net), backups, updates and reverse-proxy notes: docs/DEPLOY.md.
Privacy
Finalarr talks to your Sonarr, your media servers (Emby, Jellyfin, Plex) if you connect them, the notification channels you configure, and public metadata sources: AniList and Fribb's anime-lists (GitHub), MyAnimeList via Jikan, TVmaze, the news feeds of LiveChart.me, Anime News Network, Anime2You and Crunchyroll, Google News (the series title, for the news box; can be switched off), plus TMDB, Trakt and AnimeSchedule.net only if you add their keys. Every source can be switched off under Settings → Data sources, which also lists each one's terms. A trailer is loaded from YouTube (youtube-nocookie.com) only when you click it. It sends TVDB/AniList ids or plain search terms — never your Sonarr address, keys or library contents. No telemetry.
Development
cd backend && python3.12 -m venv .venv && . .venv/bin/activate && pip install -e '.[dev]' && pytest
cd frontend && npm ci && npm test
docker compose up --build # http://localhost:5790
e2e/run.sh # end-to-end test with a demo Sonarr
See CONTRIBUTING.md. Design notes: docs/DESIGN.md. Security issues: SECURITY.md.
Licence
GPL-3.0 — see LICENSE and THIRD_PARTY_NOTICES.md. This product uses the TMDB API but is not endorsed or certified by TMDB.
A project by <abrechen2 />.
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/abrechen2/finalarr:latestRuntime arguments
- Web UI
http://[IP]:[PORT:5790]/- Network
bridge- Shell
sh- Privileged
- false
- Extra Params
--stop-timeout 90
Template configuration
Web UI, API and Sonarr webhook
- Target
- 5790
- Default
- 5790
- Value
- 5790
Database, log and scheduler lock
- Target
- /config
- Default
- /mnt/user/appdata/finalarr
- Value
- /mnt/user/appdata/finalarr
Required, at least 20 characters (e.g. openssl rand -hex 32). Also your login.
- Target
- FINALARR_API_KEY
Required. Encrypts stored Sonarr keys and channel URLs. Generate in the Unraid terminal: openssl rand -base64 32 | tr '+/' '-_' — keep it; changing it makes stored secrets unreadable.
- Target
- FINALARR_SECRET_KEY
Optional address you open Finalarr at; adds links to messages.
- Target
- FINALARR_PUBLIC_URL
required = API key everywhere; local = no login from private addresses (behind a reverse proxy also set Trusted proxies)
- Target
- FINALARR_AUTH
- Default
- required
- Value
- required
Number of reverse proxies in front of Finalarr (e.g. 1 behind Nginx Proxy Manager)
- Target
- FINALARR_TRUSTED_PROXIES
- Default
- 0
- Value
- 0
true when you open Finalarr through a reverse proxy with HTTPS: the login cookie is then only sent over HTTPS
- Target
- FINALARR_COOKIE_SECURE
- Default
- false
- Value
- false
Optional public base URL that serves only /ical/ (e.g. through a reverse proxy), shown as the subscription address so Google or Outlook can reach the feed
- Target
- FINALARR_FEED_URL
Optional (themoviedb.org): earlier season announcements, where to watch per country, trailers
- Target
- FINALARR_TMDB_API_KEY
Country for where to watch (ISO code, e.g. DE, US, GB)
- Target
- FINALARR_WATCH_REGION
- Default
- DE
- Value
- DE
Optional (trakt.tv): another source for season announcements
- Target
- FINALARR_TRAKT_CLIENT_ID
Optional (animeschedule.net): English dub dates
- Target
- FINALARR_ANIMESCHEDULE_TOKEN
User id for files in /config
- Default
- 99
- Value
- 99
Group id for files in /config
- Default
- 100
- Value
- 100
Time zone for quiet hours
- Default
- Europe/Berlin
- Value
- Europe/Berlin