🚀 Addarr Refresh

A Telegram bot to manage your media collection through Radarr, Sonarr, and Lidarr

Addarr Refresh is a modern Telegram bot that helps you manage your media collection through Radarr, Sonarr, and Lidarr. This user-friendly fork of Addarr adds powerful new features like:

🎯 Improved search accuracy and matching
🔔 Enhanced notifications and status updates
🛠️ Interactive setup wizard for easy configuration
🌐 Multi-language support
🔒 Advanced user authentication and permissions
📊 Detailed health monitoring and statistics
🎨 Modern UI with inline keyboards and rich media
📁 Helm chart for easy deployment
🐳 Docker image for easy containerization
🔍 Validations and error handling

Whether you're managing movies, TV shows, or music, Addarr Refresh makes it simple to search, download, and organize your media library right from Telegram.

🚀 Quick Install

Linux/macOS

Open a terminal and run:

wget -qO- https://raw.githubusercontent.com/cyneric/addarr/main/scripts/install.sh | sudo bash

Windows

Open PowerShell as Administrator and run:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/cyneric/addarr/main/scripts/install.ps1'))

For more options, see 🛠️ Installation

📋 Table of Contents

🚀 Addarr Refresh

✨ Features

🎬 Movie Management
- Search and add movies through Radarr
- Preview movie posters and descriptions
- Select quality profiles and paths
- Automatic movie monitoring
📺 TV Show Management
- Add TV series via Sonarr
- Season selection support
- Quality profile management
- Automatic episode monitoring
🎵 Music Management
- Artist and album search through Lidarr
- Quality profile selection
- Automatic release monitoring
- Album organization
🛠️ Advanced Features
- 🖼️ Rich media previews with posters
- 🌍 Multi-language support
- 🔒 Secure chat-based authentication
- ⚡ Download speed control
- 📁 Custom path selection
- 🎚️ Quality profile management
- 🔄 Automatic media monitoring
- 📝 Detailed logging system
🏥 Health Monitoring
- Real-time service health checks
- Automatic service recovery detection
- Detailed version information
- Service connectivity monitoring
- Status reporting via /status command
- Configurable check intervals
- Colorized health status output

💻 System Requirements

Supported Operating Systems

Windows 10/11
Linux (Ubuntu 20.04+, Debian 10+, CentOS 8+)
macOS (10.15 Catalina or newer)

Prerequisites

Python 3.9 or higher
pip (Python package installer)
At least one of: Radarr, Sonarr, or Lidarr instance(s)
Telegram Bot Token (from @BotFather)

Python Installation

Windows

Download Python from python.org
Run the installer (make sure to check "Add Python to PATH")
Verify installation:
```
python --version
pip --version
```

Linux (Debian/Ubuntu)

# Update package list
sudo apt update

# Install Python and pip
sudo apt install python3 python3-pip

# Verify installation
python3 --version
pip3 --version

macOS

Install Homebrew if not already installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/scripts/install.sh)"

Install Python:
```
brew install python
```
Verify installation:
```
python3 --version
pip3 --version
```

🛠️ Installation

Option 1: Install Script (easy)

(Linux/macOS/Windows)

Install Addarr with a single command

Linux/macOS

Using curl:

curl -sSL https://raw.githubusercontent.com/cyneric/addarr/main/scripts/install.sh | sudo bash

or Using wget:

wget -qO- https://raw.githubusercontent.com/cyneric/addarr/main/scripts/install.sh | sudo bash

The linux/macOS installer will:

Create a dedicated installation directory at ~/.addarr
Set up a Python virtual environment
Install all required dependencies
Create the addarr command for easy access
Back up any existing installation

After installation:

Run addarr (on first run, setup wizard will start automatically)
Run addarr to start the bot

Windows

Using PowerShell:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/cyneric/addarr/main/scripts/install.ps1'))

The windows installer will:

Create a dedicated installation directory at C:\Users\<username>\AppData\Local\Addarr
Set up a Python virtual environment
Install all required dependencies
Create the addarr command for easy access
Back up any existing installation

After installation:

Run addarr (on first run, setup wizard will start automatically)
Run addarr to start the bot

Option 2: Git Clone (advanced)

(Linux/macOS/Windows)

Requires git to be installed and available in the command line.

Clone the repository

git clone https://github.com/Cyneric/Addarr.git

Change into the Addarr directory
```
cd addarr
```
Install dependencies
```
pip install -r requirements.txt
```
Start the Bot
```
python run.py
```
The bot will automatically start the setup wizard of no configuration file is found.

Option 3: Manual installation from zip file (advanced)

(Windows)

Requires python to be installed and available in the command line.

Download the zip file Download the zip file from here
Extract the zip file Extract the zip file and change into the Addarr directory
Copy or rename the config file Copy or rename the config_example.yaml file to config.yaml
Edit the config file Edit the config.yaml file with your settings.
Run configuration check
```
python run.py --check
```
Start the bot
```
python run.py
```

Option 4: Docker Installation (advanced)

(Linux/macOS/Windows)

Using Docker Compose

Clone the repository

git clone https://github.com/yourusername/addarr.git
cd addarr

Configure the bot

cp config_example.yaml config.yaml
# Edit config.yaml with your settings

Start with Docker Compose
```
docker-compose up -d
```

Using Docker standalone

Build the image
```
docker build -t addarr .
```

Run the container

docker run -d \
  --name addarr \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/logs:/app/logs \
  addarr

🎮 Usage

Available Commands

/start - Start the bot
/auth - Authenticate with the bot
/movie - Search and add movies
/series - Search and add TV shows
/music - Search and add music
/delete - Delete media
/status - Check system status
/settings - Manage settings
/help - Show help message

Authentication

Start the bot with /start
Use /auth to authenticate
Enter the password configured in config.yaml

Adding Media

Use the appropriate command (/movie, /series, /music)
Enter search term
Select from search results
Choose quality profile and path
Confirm addition

Command Line Options

The bot can be controlled through various command-line options:

# Normal startup (on first run, setup wizard will start automatically)
python run.py

# Reset the configuration and start from scratch
python run.py --reset

# Create a backup of the current configuration
python run.py --backup

# Check current configuration and service status
python run.py --check

# Show version information
python run.py --version

# Validate translation files
python run.py --validate-i18n

# Show help message and available commands
python run.py --help

Command Details

--setup: Launches the interactive setup wizard to create a new configuration
--reset: Creates a backup of the existing configuration in the backup directory and starts fresh setup
--backup: Creates a timestamped backup of the current configuration in the backup directory
--check: Displays the current status of all configured services
--version: Shows the current version of Addarr
--validate-i18n: Validates the translation files
--help: Displays help message with all available commands and their descriptions

Configuration Backups

Addarr automatically manages configuration backups:

Manual Backup: Use python run.py --backup to create a backup anytime
Auto Backup on Reset: When using --reset, the existing configuration is automatically backed up
Backup Location: All backups are stored in the backup directory with timestamps
Backup Format: config_YYYYMMDD_HHMMSS.yaml

This ensures you never lose your configuration and can easily revert to previous versions if needed.

⚙️ Configuration

Basic Configuration

telegram:
  token: "your-bot-token"
  
language: "en-us"  # Available: en-us, de-de, etc.

logging:
  debug: false
  toConsole: true
  
security:
  enableAdmin: false
  password: "your-password"

Service Configuration

radarr:
  server:
    addr: "localhost"
    port: 7878
    ssl: false
  auth:
    apikey: "your-radarr-api-key"

sonarr:
  server:
    addr: "localhost"
    port: 8989
    ssl: false
  auth:
    apikey: "your-sonarr-api-key"

lidarr:
  server:
    addr: "localhost"
    port: 8686
    ssl: false
  auth:
    apikey: "your-lidarr-api-key"

Resetting Configuration

If you want to reset your configuration and start from scratch, you can use the --reset argument when running the setup script:

python setup.py --reset

This will delete the existing config.yaml file and prompt you to create a new one.

🏥 Health Monitoring

Addarr Refresh includes a comprehensive health monitoring system that continuously checks the status of all configured services:

Features

Periodic health checks of all enabled services
Real-time service status monitoring
Automatic detection of service recovery
Detailed version information for each service
Service connectivity validation
Status reporting via /status command

Health Check Details

The health monitoring system checks:

Media Services
- Radarr connectivity and version
- Sonarr connectivity and version
- Lidarr connectivity and version
Download Clients
- SABnzbd connectivity and version
- Transmission connectivity and status

Configuration

Health checks can be configured in config.yaml:

monitoring:
  interval: 15  # Check interval in minutes
  enabled: true # Enable/disable health monitoring

Status Command

Use the /status command in Telegram to get a detailed health report:

Current status of all services
Version information
Last check time
Any service issues or warnings

Automatic Recovery

The system will:

Detect when services become unavailable
Log all service state changes
Notify when services recover
Provide detailed error information
Track service uptime and status history

🌐 Internationalization

Addarr Refresh supports multiple languages:

Supported Languages

English (en-us)
German (de-de)
Spanish (es-es)
French (fr-fr)
Italian (it-it)
Dutch (nl-be)
Polish (pl-pl)
Portuguese (pt-pt)

Adding Translations

If you want to add a new language, follow these steps:

Create a new translation file in the translations directory
Add the new language code to the language field in config.yaml
Translate the messages in the new file
Run python run.py --validate-i18n to validate the translations

🔧 Service Management

Addarr Refresh can be run as a Windows service or a Linux Systemd service:

Windows Service

Open PowerShell as Administrator

Navigate to the scripts directory:

cd C:\Users\<username>\AppData\Local\Addarr\scripts

Run the service installation script:
```
.\addarr.service.ps1
```

Manage the service:

Start-Service AddarrBot
Stop-Service AddarrBot
Restart-Service AddarrBot
Get-Service AddarrBot

Linux Systemd Service

Create the user service directory:
```
mkdir -p ~/.config/systemd/user/
```

Copy the service file:

cp ~/.addarr/scripts/addarr.service ~/.config/systemd/user/

Reload systemd:
```
systemctl --user daemon-reload
```

Enable and start the service:

systemctl --user enable addarr
systemctl --user start addarr

Enable user service persistence:
```
loginctl enable-linger $USER
```

Manage the service:

systemctl --user status addarr
systemctl --user start addarr
systemctl --user stop addarr
systemctl --user restart addarr

☁️ Deployment Options

Addarr Refresh can be deployed using Docker or Kubernetes:

Docker Deployment

Clone the repository

git clone https://github.com/Cyneric/Addarr.git
cd addarr

Configure the bot

cp config_example.yaml config.yaml
# Edit config.yaml with your settings

Start with Docker Compose
```
docker-compose up -d
```

Kubernetes Deployment

Create a Kubernetes deployment

kubectl apply -f kubernetes/deployment.yaml

Create a Kubernetes service

kubectl apply -f kubernetes/service.yaml

👨‍💻 Development

Project Structure

addarr/
├── src/                    # Source code directory
│   ├── api/               # API clients
│   │   ├── __init__.py
│   │   ├── base.py       # Base API client
│   │   ├── radarr.py     # Radarr API client
│   │   ├── sonarr.py     # Sonarr API client
│   │   ├── lidarr.py     # Lidarr API client
│   │   ├── transmission.py # Transmission API client
│   │   └── sabnzbd.py    # SABnzbd API client
│   ├── bot/              # Telegram bot components
│   │   ├── __init__.py
│   │   ├── handlers/     # Command handlers
│   │   │   ├── __init__.py
│   │   │   ├── auth.py   # Authentication handler
│   │   │   ├── media.py  # Media management handler
│   │   │   ├── start.py  # Start/menu handler
│   │   │   ├── help.py   # Help handler
│   │   │   ├── sabnzbd.py # SABnzbd handler
│   │   │   └── transmission.py # Transmission handler
│   │   └── keyboards.py  # Keyboard layouts
│   ├── config/           # Configuration management
│   │   ├── __init__.py
│   │   └── settings.py   # Configuration handling
│   ├── services/         # Business logic services
│   │   ├── __init__.py
│   │   ├── media.py      # Media service
│   │   ├── translation.py # Translation service
│   │   ├── transmission.py # Transmission service
│   │   └── sabnzbd.py    # SABnzbd service
│   ├── utils/            # Utility functions
│   │   ├── __init__.py
│   │   ├── logger.py     # Logging setup
│   │   └── validate_translations.py # Translation validation
│   ├── __init__.py
│   └── main.py          # Application entry point
├── translations/         # Translation files
│   ├── addarr.template.yml # Translation template
│   ├── addarr.en-us.yml
│   ├── addarr.de-de.yml
│   ├── addarr.es-es.yml
│   ├── addarr.fr-fr.yml
│   ├── addarr.it-it.yml
│   ├── addarr.nl-be.yml
│   ├── addarr.pl-pl.yml
│   └── addarr.pt-pt.yml
├── config.yaml          # User configuration
├── config_example.yaml  # Example configuration
├── run.py              # Application launcher
├── requirements.txt    # Python dependencies
├── Dockerfile         # Docker build file
└── docker-compose.yml # Docker compose config

Development Setup

Create development environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

Install development dependencies

pip install -r requirements.txt
pip install -r requirements-dev.txt  # Development dependencies

Set up pre-commit hooks
```
pre-commit install
```
Run tests
```
pytest tests/
```

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Christian Blank (@cyneric)

🙏 Acknowledgments

This project is a modernized fork of Addarr, building upon its foundation with enhanced features, improved architecture, and a more robust codebase. Special thanks to @Waterboy1602 for creating the original project that made this possible.

🔗 python-telegram-bot 🔗 Radarr 🔗 Sonarr 🔗 Lidarr

Made with ❤️

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.github		.github
helm		helm
scripts		scripts
src		src
translations		translations
.dockerignore		.dockerignore
.flake8		.flake8
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
changelog.yaml		changelog.yaml
config_example.yaml		config_example.yaml
docker-compose.yml		docker-compose.yml
project_structure		project_structure
requirements.txt		requirements.txt
run.py		run.py

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

🚀 Addarr Refresh

🚀 Quick Install

Linux/macOS

Windows

📋 Table of Contents

✨ Features

💻 System Requirements

Supported Operating Systems

Prerequisites

Python Installation

Windows

Linux (Debian/Ubuntu)

macOS

🛠️ Installation

Option 1: Install Script (easy)

Linux/macOS

Windows

Option 2: Git Clone (advanced)

Option 3: Manual installation from zip file (advanced)

Option 4: Docker Installation (advanced)

Using Docker Compose

Using Docker standalone

🎮 Usage

Available Commands

Authentication

Adding Media

Command Line Options

Command Details

Configuration Backups

⚙️ Configuration

Basic Configuration

Service Configuration

Resetting Configuration

🏥 Health Monitoring

Features

Health Check Details

Configuration

Status Command

Automatic Recovery

🌐 Internationalization

Supported Languages

Adding Translations

🔧 Service Management

Windows Service

Linux Systemd Service

☁️ Deployment Options

Docker Deployment

Kubernetes Deployment

👨‍💻 Development

Project Structure

Development Setup

🤝 Contributing

📄 License

Author

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages