starred/MediaManager
1
0
Fork 0
mirror of https://github.com/maxdorninger/MediaManager.git synced 2026-04-17 23:53:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

GITBOOK-9: No subject

Browse Source
This commit is contained in:
maxidorninger
2026-01-05 19:12:55 +00:00
committed by gitbook-bot
parent 1b2d99922c
commit 9c7679101f
46 changed files with 1773 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/configuration/README.md Normal file
View File

@@ -0,0 +1,71 @@
# Configuration
MediaManager uses a TOML configuration file (`config.toml`) for all backend settings. This centralized configuration approach makes it easier to manage, backup, and share your MediaManager setup.
Frontend settings are configured through environment variables in your `docker-compose.yaml` file.
## Configuration File Location
{% hint style="warning" %}
Note that MediaManager may need to be restarted for changes in the config file to take effect.
{% endhint %}
Your `config.toml` file should be in the directory that's mounted to `/app/config/config.toml` inside the container:
```yaml
volumes:
- ./config:/app/config
```
You can change the configuration directory with the following environment variable:
* `CONFIG_DIR`\
Directory that contains `config.toml`. Default is `/app/config`. Example: `/etc/mediamanager/`.
## Configuration Sections
The configuration is organized into the following sections:
* `[misc]` - General settings
* `[database]` - Database settings
* `[auth]` - Authentication settings
* `[notifications]` - Notification settings (Email, Gotify, Ntfy, Pushover)
* `[torrents]` - Download client settings (qBittorrent, Transmission, SABnzbd)
* `[indexers]` - Indexer settings (Prowlarr and Jackett )
* `[metadata]` - TMDB and TVDB settings
## Configuring Secrets
For sensitive information like API keys, passwords, and secrets, you should use environment variables. You can actually set every configuration value through environment variables. For example, to set the `token_secret` value for authentication, with a .toml file you would use:
```toml
[auth]
token_secret = "your_super_secret_key_here"
```
But you can also set it through an environment variable:
```none
MEDIAMANAGER_AUTH__TOKEN_SECRET = "your_super_secret_key_here"
```
or another example with the OIDC client secret:
```toml
[auth]
...
[auth.openid_connect]
client_secret = "your_client_secret_from_provider"
```
env variable:
```none
MEDIAMANAGER_AUTH__OPENID_CONNECT__CLIENT_SECRET = "your_client_secret_from_provider"
```
So for every config "level", you basically have to take the name of the value and prepend it with the section names in uppercase with 2 underscores as delimiters and `MEDIAMANAGER_` as the prefix.
{% hint style="warning" %}
Note that not every env variable starts with `MEDIAMANAGER_`; this prefix only applies to env variables which replace/overwrite values in the config file. Variables like the `CONFIG_DIR` env variable must not be prefixed.
{% endhint %}

85
docs/configuration/authentication.md Normal file
View File

@@ -0,0 +1,85 @@
---
description: >-
MediaManager supports multiple authentication methods. Email/password
authentication is the default, but you can also enable OpenID Connect (OAuth
2.0) for integration with external identity providers
---
# Authentication
All authentication settings are configured in the `[auth]` section of your `config.toml` file.
## General Authentication Settings (`[auth]`)
* `token_secret`\
Strong secret key for signing JWTs (create with `openssl rand -hex 32`). This is required.
* `session_lifetime`\
Lifetime of user sessions in seconds. Default is `86400` (1 day).
* `admin_emails`\
A list of email addresses for administrator accounts. This is required.
* `email_password_resets`\
Enables password resets via email. Default is `false`.
{% hint style="info" %}
To use email password resets, you must also configure SMTP settings in the `[notifications.smtp_config]` section.
{% endhint %}
{% hint style="info" %}
When setting up MediaManager for the first time, you should add your email to `admin_emails` in the `[auth]` config section. MediaManager will then use this email instead of the default admin email. Your account will automatically be created as an admin account, allowing you to manage other users, media and settings.
{% endhint %}
## OpenID Connect Settings (`[auth.openid_connect]`)
OpenID Connect allows you to integrate with external identity providers like Google, Microsoft Azure AD, Keycloak, or any other OIDC-compliant provider.
* `enabled`\
Set to `true` to enable OpenID Connect authentication. Default is `false`.
* `client_id`\
Client ID provided by your OpenID Connect provider.
* `client_secret`\
Client secret provided by your OpenID Connect provider.
* `configuration_endpoint`\
OpenID Connect configuration endpoint URL. Do not include a trailing slash. Usually ends with `/.well-known/openid-configuration`.
* `name`\
Display name for the OpenID Connect provider shown on the login page.
### Configuration for your OpenID Connect Provider
#### Redirect URI
The OpenID server will likely require a redirect URI. This URL will usually look something like this:
```none
{MEDIAMANAGER_URL}/api/v1/auth/oauth/callback
```
{% hint style="warning" %}
It is very important that you set the correct callback URI, otherwise it won't work!
{% endhint %}
#### Authentik Example
Here is an example configuration for the OpenID Connect provider for Authentik.
![authentik-redirect-url-example](<../.gitbook/assets/authentik redirect url example.png>)
## Example Configuration
Here's a complete example of the authentication section in your `config.toml`:
{% code title="config.toml" %}
```toml
[auth]
token_secret = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
session_lifetime = 604800 # 1 week
admin_emails = ["admin@example.com", "manager@example.com"]
email_password_resets = true
[auth.openid_connect]
enabled = true
client_id = "mediamanager-client"
client_secret = "your-secret-key-here"
configuration_endpoint = "https://auth.example.com/.well-known/openid-configuration"
name = "Authentik"
```
{% endcode %}

45
docs/configuration/backend.md Normal file
View File

@@ -0,0 +1,45 @@
---
description: >-
These settings configure the core backend application through the config.toml
file. All backend configuration is now centralized in this TOML file instead
of environment variables.
---
# Backend
## General Settings (`[misc]`)
* `frontend_url`\
The URL the frontend will be accessed from. This is required. Do not include a trailing slash. Default is `http://localhost:8000`.
Example: if you are accessing MediaManager at `http://example.com/media`, set this to `http://example.com/media`.
If you are accessing MediaManager at the root of a domain, e.g. `https://mediamanager.example.com`, set this to `https://mediamanager.example.com`.
`frontend_url` does not affect where the server binds. It also does not configure a base path prefix. For prefixes, see [URL Prefix](../advanced-features/url-prefix.md).
* `cors_urls`\
A list of origins you are going to access the API from. Do not include trailing slashes.
* `development`\
Set to `true` to enable development mode. Default is `false`.
## Example Configuration
Here's a complete example of the general settings section in your `config.toml`:
{% code title="config.toml" %}
```toml
[misc]
# REQUIRED: Change this to match your actual frontend domain.
frontend_url = "http://mediamanager.dev"
cors_urls = ["http://localhost:8000"]
# Optional: Development mode (set to true for debugging)
development = false
```
{% endcode %}
{% hint style="info" %}
The `frontend_url` is the most important setting to configure correctly. Make sure it matches your actual deployment URLs.
{% endhint %}

53
docs/configuration/custom-libraries.md Normal file
View File

@@ -0,0 +1,53 @@
# Custom Libraries
MediaManager supports custom libraries, allowing you to add multiple folders for your movies and TV series. This feature is useful if you organize your media into different directories. For example, you might have separate folders for "Action" movies and "Comedy" movies, or "Live Action" TV shows and "Animated" TV shows.
## Configuration
Custom libraries are configured in the `misc` section in the `config.toml` file. You can add as many libraries as you need.
{% hint style="info" %}
You are not limited to `/data/tv` or `/data/movies`, you can choose the entire path freely!
{% endhint %}
### Movie Libraries
To add custom movie libraries, add a `[[misc.movie_libraries]]` section for each library. Each library requires a `name` and a `path`.
Example — configuring two movie libraries:
```toml
[misc]
# ... other misc settings
[[misc.movie_libraries]]
name = "Action"
path = "/data/movies/action"
[[misc.movie_libraries]]
name = "Comedy"
path = "/data/movies/comedy"
```
In this example, MediaManager will scan both `/data/movies/action` and `/data/movies/comedy` for movies.
### TV Show Libraries
Similarly, to add custom TV show libraries, add a `[[misc.tv_libraries]]` section for each library. Each library requires a `name` and a `path`.
Example — configuring two TV show libraries:
```toml
[misc]
# ... other misc settings
[[misc.tv_libraries]]
name = "Live Action"
path = "/data/tv/live-action"
[[misc.tv_libraries]]
name = "Animation"
path = "/data/tv/animation"
```

35
docs/configuration/database.md Normal file
View File

@@ -0,0 +1,35 @@
# Database
Database settings are configured in the `[database]` section of your `config.toml` file. MediaManager uses PostgreSQL as its database backend.
## Database Settings (`[database]`)
* `host`\
Hostname or IP of the PostgreSQL server. Default is `localhost`.
* `port`\
Port number of the PostgreSQL server. Default is `5432`.
* `user`\
Username for the PostgreSQL connection. Default is `MediaManager`.
* `password`\
Password for the PostgreSQL user. Default is `MediaManager`.
* `dbname`\
Name of the PostgreSQL database. Default is `MediaManager`.
## Example Configuration
Here's a complete example of the database section in your `config.toml`:
{% code title="config.toml" %}
```toml
[database]
host = "db"
port = 5432
user = "MediaManager"
password = "your_secure_password"
dbname = "MediaManager"
```
{% endcode %}
{% hint style="info" %}
In docker-compose deployments the container name is simultaneously its hostname, so you can use "db" or "postgres" as host.
{% endhint %}

132
docs/configuration/download-clients.md Normal file
View File

@@ -0,0 +1,132 @@
# Download Clients
Download client settings are configured in the `[torrents]` section of your `config.toml` file. MediaManager supports both qBittorrent and SABnzbd as download clients.
## qBittorrent Settings (`[torrents.qbittorrent]`)
qBittorrent is a popular BitTorrent client that MediaManager can integrate with for downloading torrents.
* `enabled`\
Set to `true` to enable qBittorrent integration. Default is `false`.
* `host`\
Hostname or IP of the qBittorrent server. Include the protocol (http/https).
* `port`\
Port of the qBittorrent Web UI/API. Default is `8080`.
* `username`\
Username for qBittorrent Web UI authentication. Default is `admin`.
* `password`\
Password for qBittorrent Web UI authentication. Default is `admin`.
## Transmission Settings (`[torrents.transmission]`)
{% hint style="info" %}
The downloads path in Transmission and MediaManager must be the same, i.e. the path `/data/torrents` must link to the same volume for both containers.
{% endhint %}
Transmission is a BitTorrent client that MediaManager can integrate with for downloading torrents.
* `enabled`\
Set to `true` to enable Transmission integration. Default is `false`.
* `username`\
Username for Transmission RPC authentication.
* `password`\
Password for Transmission RPC authentication.
* `https_enabled`\
Set to `true` if your Transmission RPC endpoint uses HTTPS. Default is `true`.
* `host`\
Hostname or IP of the Transmission server (without protocol).
* `port`\
Port of the Transmission RPC endpoint. Default is `9091`.
* `path`\
RPC request path target. Usually `/transmission/rpc`.
## SABnzbd Settings (`[torrents.sabnzbd]`)
SABnzbd is a Usenet newsreader that MediaManager can integrate with for downloading NZB files.
* `enabled`\
Set to `true` to enable SABnzbd integration. Default is `false`.
* `host`\
Hostname or IP of the SABnzbd server, it needs to include `http(s)://`.
* `port`\
Port of the SABnzbd API. Default is `8080`.
* `api_key`\
API key for SABnzbd. You can find this in SABnzbd's configuration under "General" → "API Key".
* `base_path`\
API base path for SABnzbd. It usually ends with `/api`, the default is `/api`.
## Example Configuration
Here's a complete example of the download clients section in your `config.toml`:
{% code title="config.toml" %}
```toml
[torrents]
# qBittorrent configuration
[torrents.qbittorrent]
enabled = true
host = "http://qbittorrent"
port = 8080
username = "admin"
password = "your_secure_password"
# Transmission configuration
[torrents.transmission]
enabled = false
username = "admin"
password = "your_secure_password"
https_enabled = true
host = "transmission"
port = 9091
path = "/transmission/rpc"
# SABnzbd configuration
[torrents.sabnzbd]
enabled = false
host = "http://sabnzbd"
port = 8080
api_key = "your_sabnzbd_api_key"
```
{% endcode %}
## Docker Compose Integration
When using Docker Compose, make sure your download clients are accessible from the MediaManager backend:
{% code title="docker-compose.yml" %}
```yaml
services:
# MediaManager backend
backend:
image: ghcr.io/maxdorninger/mediamanager/backend:latest
# ... other configuration ...
# qBittorrent service
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
ports:
- "8080:8080"
environment:
- WEBUI_PORT=8080
volumes:
- ./data/torrents:/downloads
# ... other configuration ...
# SABnzbd service
sabnzbd:
image: lscr.io/linuxserver/sabnzbd:latest
ports:
- "8081:8080"
volumes:
- ./data/usenet:/downloads
# ... other configuration ...
```
{% endcode %}
{% hint style="warning" %}
You should enable only one BitTorrent and only one Usenet Download Client at any time.
{% endhint %}
{% hint style="info" %}
Make sure the download directories in your download clients are accessible to MediaManager for proper file management and organization.
{% endhint %}

69
docs/configuration/indexers.md Normal file
View File

@@ -0,0 +1,69 @@
# Indexers
Indexer settings are configured in the `[indexers]` section of your `config.toml` file. MediaManager supports both Prowlarr and Jackett as indexer providers.
## Prowlarr (`[indexers.prowlarr]`)
* `enabled`\
Set to `true` to enable Prowlarr. Default is `false`.
* `url`\
Base URL of your Prowlarr instance.
* `api_key`\
API key for Prowlarr. You can find this in Prowlarr's settings under General.
* `timeout_seconds`\
Timeout in seconds for requests to Prowlarr. Default is `60`.
{% hint style="warning" %}
Symptoms of timeouts are typically no search results ("No torrents found!") in conjunction with logs showing read timeouts.
{% endhint %}
<details>
<summary>Example timeout log</summary>
```none
DEBUG - media_manager.indexer.utils -
follow_redirects_to_final_torrent_url():
An error occurred during the request for <some-url>:
HTTPConnectionPool(host='<some-host>', port=<some-port>):
Read timed out. (read timeout=10)
```
</details>
***
## Jackett (`[indexers.jackett]`)
* `enabled`\
Set to `true` to enable Jackett. Default is `false`.
* `url`\
Base URL of your Jackett instance.
* `api_key`\
API key for Jackett. You can find this in Jackett's dashboard.
* `indexers`\
List of indexer names to use with Jackett.
* `timeout_seconds`\
Timeout in seconds for requests to Jackett. Refer to the Prowlarr section for details.
***
## Example Configuration
{% code title="config.toml" %}
```toml
[indexers]
[indexers.prowlarr]
enabled = true
url = "http://prowlarr:9696"
api_key = "your_prowlarr_api_key"
timeout_seconds = 60
[indexers.jackett]
enabled = false
url = "http://jackett:9117"
api_key = "your_jackett_api_key"
indexers = ["1337x", "rarbg"]
timeout_seconds = 60
```
{% endcode %}

12
docs/configuration/logging.md Normal file
View File

@@ -0,0 +1,12 @@
# Logging
MediaManager automatically logs events and errors to help with troubleshooting and monitoring. These logs are emitted to the console (stdout) by default, and to a json-formatted log file.
## Configuring Logging
The following are configured as environment variables.
* `LOG_FILE`\
Path to the JSON log file. Default is `/app/config/media_manager.log`. The directory must exist and be writable.
* `MEDIAMANAGER_LOG_LEVEL`\
Logging level. Default is `INFO`. Supported values: `DEBUG`, `INFO`, `WARNING`, `ERROR`.

98
docs/configuration/notifications.md Normal file
View File

@@ -0,0 +1,98 @@
# Notifications
These settings are configured in the `[notifications]` section of your `config.toml` file.
## SMTP Configuration (`[notifications.smtp_config]`)
For sending emails, MediaManager uses the SMTP protocol. You can use any SMTP server, like Gmail or SMTP2GO.
* `smtp_host`\
Hostname of the SMTP server.
* `smtp_port`\
Port of the SMTP server.
* `smtp_user`\
Username for the SMTP server.
* `smtp_password`\
Password (or app password) for the SMTP server.
* `from_email`\
From-address used when sending emails.
* `use_tls`\
Set to `true` to use TLS for the SMTP connection. Default is `true`.
## Email Notifications (`[notifications.email_notifications]`)
Controls which emails receive notifications.
* `enabled`\
Set to `true` to enable email notifications. Default is `false`.
* `emails`\
List of email addresses to send notifications to.
## Gotify Notifications (`[notifications.gotify]`)
* `enabled`\
Set to `true` to enable Gotify notifications. Default is `false`.
* `api_key`\
API key for Gotify.
* `url`\
Base URL of your Gotify instance. Do not include a trailing slash.
## Ntfy Notifications (`[notifications.ntfy]`)
* `enabled`\
Set to `true` to enable Ntfy notifications. Default is `false`.
* `url`\
URL of your ntfy instance plus the topic.
## Pushover Notifications (`[notifications.pushover]`)
* `enabled`\
Set to `true` to enable Pushover notifications. Default is `false`.
* `api_key`\
API key for Pushover.
* `user`\
User key for Pushover.
## Example Configuration
Here's a complete example of the notifications section in your `config.toml`:
{% code title="config.toml" %}
```toml
[notifications]
# SMTP settings for email notifications and password resets
[notifications.smtp_config]
smtp_host = "smtp.gmail.com"
smtp_port = 587
smtp_user = "your-email@gmail.com"
smtp_password = "your-app-password"
from_email = "mediamanager@example.com"
use_tls = true
# Email notification settings
[notifications.email_notifications]
enabled = true
emails = ["admin@example.com", "notifications@example.com"]
# Gotify notification settings
[notifications.gotify]
enabled = true
api_key = "your_gotify_api_key"
url = "https://gotify.example.com"
# Ntfy notification settings
[notifications.ntfy]
enabled = false
url = "https://ntfy.sh/your-private-topic"
# Pushover notification settings
[notifications.pushover]
enabled = false
api_key = "your_pushover_api_key"
user = "your_pushover_user_key"
```
{% endcode %}
{% hint style="info" %}
You can enable multiple notification methods simultaneously. For example, you could have both email and Gotify notifications enabled at the same time.
{% endhint %}

141
docs/configuration/scoring-rulesets.md Normal file
View File

@@ -0,0 +1,141 @@
# Scoring Rulesets
Scoring rulesets in MediaManager allow you to flexibly control which releases are preferred or avoided when searching for media. Each ruleset is a collection of scoring rules that can be assigned to one or more libraries. When MediaManager evaluates releases, it applies the relevant ruleset(s) to adjust the score of each result, influencing which releases are selected for download.
## How Rulesets Work
* Rulesets are defined in the configuration and contain a list of rule names and the libraries they apply to.
* Scoring rules can target keywords in release titles or specific indexer flags.
* When searching for a release, MediaManager checks which library the media belongs to and applies the corresponding ruleset.
## Rules
Rules define how MediaManager scores releases based on their titles or indexer flags. You can create rules that:
* Prefer releases with specific codecs (e.g., H.265 over H.264).
* Avoid releases with certain keywords (e.g., "CAM", "TS", "Nuked").
* Reject releases that do not meet certain criteria (e.g., non-freeleech releases).
* and more.
{% hint style="info" %}
The keywords and flags are compared case-insensitively.
{% endhint %}
### Title Rules
Title rules allow you to adjust the score of a release based on the presence (or absence) of specific keywords in the release title. This is useful for preferring or avoiding certain encodings, sources, or other characteristics that are typically included in release names.
Each title rule consists of:
* `name`\
A unique identifier for the rule.
* `keywords`\
List of keywords to search for in the release title.
* `score_modifier`\
Amount to add or subtract from the score if a keyword matches.
* `negate`\
If `true`, the rule applies when none of the keywords are present.
Examples for Title Rules
{% code title="config.toml" %}
```toml
[[indexers.title_scoring_rules]]
name = "prefer_h265"
keywords = ["h265", "hevc", "x265"]
score_modifier = 100
negate = false
[[indexers.title_scoring_rules]]
name = "avoid_cam"
keywords = ["cam", "ts"]
score_modifier = -10000
negate = false
```
{% endcode %}
* The first rule increases the score for releases containing "h265", "hevc", or "x265".
* The second rule heavily penalizes releases containing "cam" or "ts".
If `negate` is set to `true`, the `score_modifier` is applied only if none of the keywords are found in the title.
### Indexer Flag Rules
Indexer flag rules adjust the score based on flags provided by the indexer (such as `freeleech`, `nuked`, etc). These flags are often used to indicate special properties or warnings about a release.
Each indexer flag rule consists of:
* `name`\
A unique identifier for the rule.
* `flags`\
List of indexer flags to match.
* `score_modifier`\
Amount to add or subtract from the score if a flag matches.
* `negate`\
If `true`, the rule applies when none of the flags are present.
Examples for Indexer Flag Rules
{% code title="config.toml" %}
```toml
[[indexers.indexer_flag_scoring_rules]]
name = "reject_non_freeleech"
flags = ["freeleech", "freeleech75"]
score_modifier = -10000
negate = true
[[indexers.indexer_flag_scoring_rules]]
name = "reject_nuked"
flags = ["nuked"]
score_modifier = -10000
negate = false
```
{% endcode %}
* The first rule penalizes releases that do not have the "freeleech" or "freeleech75" flag.
* The second rule penalizes releases that are marked as "nuked".
If `negate` is set to `true`, the `score_modifier` is applied only if none of the flags are present on the release.
## Example
{% code title="config.toml" %}
```toml
[[indexers.scoring_rule_sets]]
name = "default"
libraries = ["ALL_TV", "ALL_MOVIES"]
rule_names = ["prefer_h265", "avoid_cam", "reject_nuked"]
[[indexers.scoring_rule_sets]]
name = "strict_quality"
libraries = ["ALL_MOVIES"]
rule_names = ["prefer_h265", "avoid_cam", "reject_non_freeleech"]
```
{% endcode %}
## Libraries
The libraries that are mentioned in the preceding example are explained in greater detail in the [Library config section](custom-libraries.md).
### Special Libraries
You can use special library names in your rulesets:
* `ALL_TV`: Applies the ruleset to all TV libraries.
* `ALL_MOVIES`: Applies the ruleset to all movie libraries.
* `Default`: Applies the ruleset to all media that is not part of a custom library.
This allows you to set global rules for all TV or movie content, or provide fallback rules for uncategorized media.
{% hint style="info" %}
You don't need to create lots of libraries with different directories, multiple libraries can share the same directory. You can set multiple (unlimited) libraries to the default directory `/data/movies` or `/data/tv` and use different rulesets with them.
{% endhint %}
## Relation to Sonarr/Radarr Profiles
MediaManager's scoring rules and rulesets system is an alternative to Sonarr's Quality, Custom, and Release Profiles. This system is designed to be more intuitive and flexible.
* Quality Profiles: Use scoring rules to prefer or avoid certain codecs, resolutions, or other quality indicators.
* Custom/Release Profiles: Use title or flag-based rules to match or exclude releases based on keywords or indexer flags.
This approach provides a powerful and transparent way to fine-tune your automation.