quasarr 1.4.1__py3-none-any.whl → 1.20.4__py3-none-any.whl

quasarr/storage/config.py

@@ -26,12 +26,28 @@ class Config(object):
             ("device", "str", ""),
         ],
         'Hostnames': [
+            ("al", "secret", ""),
+            ("by", "secret", ""),
             ("dd", "secret", ""),
+            ("dj", "secret", ""),
             ("dt", "secret", ""),
             ("dw", "secret", ""),
             ("fx", "secret", ""),
+            ("he", "secret", ""),
+            ("mb", "secret", ""),
+            ("nk", "secret", ""),
             ("nx", "secret", ""),
-            ("sf", "secret", "")
+            ("sf", "secret", ""),
+            ("sj", "secret", ""),
+            ("sl", "secret", ""),
+            ("wd", "secret", "")
+        ],
+        'FlareSolverr': [
+            ("url", "str", ""),
+        ],
+        'AL': [
+            ("user", "secret", ""),
+            ("password", "secret", "")
         ],
         'DD': [
             ("user", "secret", ""),
@@ -54,10 +70,10 @@ class Config(object):
                 self._section) or self._set_default_config(self._section)
             self.__config__ = self._read_config(self._section)
         except configparser.DuplicateSectionError:
-            print('Doppelte Sektion in der Konfigurationsdatei.')
+            print('Duplicate Section in Config File')
             raise
-        except:
-            print('Ein unbekannter Fehler in der Konfigurationsdatei ist aufgetreten.')
+        except Exception as e:
+            print(f'Unknown error while reading config file: {e}')
             raise
 
     def _set_default_config(self, section):

quasarr/storage/setup.py

@@ -5,12 +5,14 @@
 import os
 import sys
 
+import requests
 from bottle import Bottle, request
 
 import quasarr
-import quasarr.downloads.sources.dd
-from quasarr.downloads.sources import dd
-from quasarr.downloads.sources import nx
+import quasarr.providers.html_images as images
+import quasarr.providers.sessions.al
+import quasarr.providers.sessions.dd
+import quasarr.providers.sessions.nx
 from quasarr.providers.html_templates import render_button, render_form, render_success, render_fail
 from quasarr.providers.log import info
 from quasarr.providers.shared_state import extract_valid_hostname
@@ -65,54 +67,157 @@ def path_config(shared_state):
     return Server(app, listen='0.0.0.0', port=shared_state.values['port']).serve_temporarily()
 
 
+def hostname_form_html(shared_state, message):
+    hostname_fields = '''
+    <label for="{id}" style="display:inline-flex; align-items:center; gap:4px;">{label}{img_html}</label>
+    <input type="text" id="{id}" name="{id}" placeholder="example.com" autocorrect="off" autocomplete="off" value="{value}"><br>
+    '''
+
+    field_html = []
+    hostnames = Config('Hostnames')  # Load once outside the loop
+    for label in shared_state.values["sites"]:
+        field_id = label.lower()
+        img_html = ''
+        try:
+            img_data = getattr(images, field_id)
+            if img_data:
+                img_html = f' <img src="{img_data}" width="16" height="16" style="filter: blur(2px);" alt="{label} icon">'
+        except AttributeError:
+            pass
+
+        # Get the current value (if any and non-empty)
+        current_value = hostnames.get(field_id)
+        if not current_value:
+            current_value = ''  # Ensure it's empty if None or ""
+
+        field_html.append(hostname_fields.format(
+            id=field_id,
+            label=label,
+            img_html=img_html,
+            value=current_value
+        ))
+
+    hostname_form_content = "".join(field_html)
+    button_html = render_button("Save", "primary", {"type": "submit"})
+
+    template = """
+<div id="message" style="margin-bottom:0.5em;">{message}</div>
+<div id="error-msg" style="color:red; margin-bottom:1em;"></div>
+
+<form action="/api/hostnames" method="post" onsubmit="return validateHostnames(this)">
+    {hostname_form_content}
+    {button}
+</form>
+
+<script>
+  function validateHostnames(form) {{
+    var errorDiv = document.getElementById('error-msg');
+    errorDiv.textContent = '';
+
+    var inputs = form.querySelectorAll('input[type="text"]');
+    for (var i = 0; i < inputs.length; i++) {{
+      if (inputs[i].value.trim() !== '') {{
+        return true;
+      }}
+    }}
+
+    errorDiv.textContent = 'Please fill in at least one hostname!';
+    inputs[0].focus();
+    return false;
+  }}
+</script>
+"""
+    return template.format(
+        message=message,
+        hostname_form_content=hostname_form_content,
+        button=button_html
+    )
+
+
+def save_hostnames(shared_state, timeout=5, first_run=True):
+    hostnames = Config('Hostnames')
+
+    # Collect submitted hostnames, validate, and track errors
+    valid_domains = {}
+    errors = {}
+
+    for site_key in shared_state.values['sites']:
+        shorthand = site_key.lower()
+        raw_value = request.forms.get(shorthand)
+        # treat missing or empty string as intentional clear, no validation
+        if raw_value is None or raw_value.strip() == '':
+            continue
+
+        # non-empty submission: must validate
+        result = extract_valid_hostname(raw_value, shorthand)
+        domain = result.get('domain')
+        message = result.get('message', 'Error checking the hostname you provided!')
+        if domain:
+            valid_domains[site_key] = domain
+        else:
+            errors[site_key] = message
+
+    # Filter out any accidental empty domains and require at least one valid hostname overall
+    valid_domains = {k: d for k, d in valid_domains.items() if d}
+    if not valid_domains:
+        # report last or generic message
+        fail_msg = next(iter(errors.values()), 'No valid hostname provided!')
+        return render_fail(fail_msg)
+
+    # Save: valid ones, explicit empty for those omitted cleanly, leave untouched if error
+    changed_sites = []
+    for site_key in shared_state.values['sites']:
+        shorthand = site_key.lower()
+        raw_value = request.forms.get(shorthand)
+        # determine if change applies
+        if site_key in valid_domains:
+            new_val = valid_domains[site_key]
+            old_val = hostnames.get(shorthand) or ''
+            if old_val != new_val:
+                hostnames.save(shorthand, new_val)
+                changed_sites.append(shorthand)
+        elif raw_value is None:
+            # no submission: leave untouched
+            continue
+        elif raw_value.strip() == '':
+            old_val = hostnames.get(shorthand) or ''
+            if old_val != '':
+                hostnames.save(shorthand, '')
+
+    quasarr.providers.web_server.temp_server_success = True
+
+    # Build success message, include any per-site errors
+    success_msg = 'At least one valid hostname set!'
+    if errors:
+        optional_text = "<br>".join(f"{site}: {msg}" for site, msg in errors.items()) + "<br>"
+    else:
+        optional_text = "All provided hostnames are valid.<br>"
+
+    if not first_run:
+        # Append restart notice for specific sites that actually changed
+        for site in changed_sites:
+            if site.lower() in {'al', 'dd', 'nx'}:
+                optional_text += f"{site.upper()}: You must restart Quasarr and follow additional steps to start using this site.<br>"
+
+    return render_success(success_msg, timeout, optional_text=optional_text)
+
+
 def hostnames_config(shared_state):
     app = Bottle()
 
     @app.get('/')
     def hostname_form():
-        hostname_fields = '''
-        <label for="{id}">{label}</label>
-        <input type="text" id="{id}" name="{id}" placeholder="example.com" autocorrect="off" autocomplete="off"><br>
-        '''
-
-        hostname_form_content = "".join(
-            [hostname_fields.format(id=label.lower(), label=label) for label in shared_state.values["sites"]])
-
-        hostname_form_html = f'''
-        <form action="/api/hostnames" method="post">
-            {hostname_form_content}
-            {render_button("Save", "primary", {"type": "submit"})}
-        </form>
-        '''
-
-        return render_form("Set at least one valid hostname", hostname_form_html)
+        message = """<p>
+          If you're having trouble setting this up, take a closer look at 
+          <a href="https://github.com/rix1337/Quasarr?tab=readme-ov-file#instructions" target="_blank" rel="noopener noreferrer">
+            step one of these instructions.
+          </a>
+        </p>"""
+        return render_form("Set at least one valid hostname", hostname_form_html(shared_state, message))
 
     @app.post("/api/hostnames")
     def set_hostnames():
-        hostnames = Config('Hostnames')
-
-        hostname_set = False
-
-        for key in shared_state.values["sites"]:
-            shorthand = key.lower()
-            hostname = request.forms.get(shorthand)
-            try:
-                if hostname:
-                    hostname = extract_valid_hostname(hostname, shorthand)
-            except Exception as e:
-                info(f"Error extracting domain from {hostname}: {e}")
-                continue
-
-            if hostname:
-                hostnames.save(key, hostname)
-                hostname_set = True
-
-        if hostname_set:
-            quasarr.providers.web_server.temp_server_success = True
-            return render_success("At least one valid hostname set",
-                                  5)
-        else:
-            return render_fail("No valid hostname provided!")
+        return save_hostnames(shared_state)
 
     info(f'Hostnames not set. Starting web server for config at: "{shared_state.values['internal_address']}".')
     info("Please set at least one valid hostname there!")
@@ -145,7 +250,7 @@ def hostname_credentials_config(shared_state, shorthand, domain):
         return render_form(f"Set User and Password for {shorthand}", form_html)
 
     @app.post("/api/credentials/<sh>")
-    def set_nx_credentials(sh):
+    def set_credentials(sh):
         user = request.forms.get('user')
         password = request.forms.get('password')
         config = Config(shorthand)
@@ -154,12 +259,16 @@ def hostname_credentials_config(shared_state, shorthand, domain):
             config.save("user", user)
             config.save("password", password)
 
+            if sh.lower() == "al":
+                if quasarr.providers.sessions.al.create_and_persist_session(shared_state):
+                    quasarr.providers.web_server.temp_server_success = True
+                    return render_success(f"{sh} credentials set successfully", 5)
             if sh.lower() == "dd":
-                if dd.create_and_persist_session(shared_state):
+                if quasarr.providers.sessions.dd.create_and_persist_session(shared_state):
                     quasarr.providers.web_server.temp_server_success = True
                     return render_success(f"{sh} credentials set successfully", 5)
             if sh.lower() == "nx":
-                if nx.create_and_persist_session(shared_state):
+                if quasarr.providers.sessions.nx.create_and_persist_session(shared_state):
                     quasarr.providers.web_server.temp_server_success = True
                     return render_success(f"{sh} credentials set successfully", 5)
 
@@ -175,15 +284,70 @@ def hostname_credentials_config(shared_state, shorthand, domain):
     return Server(app, listen='0.0.0.0', port=shared_state.values['port']).serve_temporarily()
 
 
+def flaresolverr_config(shared_state):
+    app = Bottle()
+
+    @app.get('/')
+    def url_form():
+        form_content = '''
+        <span><a href="https://github.com/FlareSolverr/FlareSolverr?tab=readme-ov-file#installation">A local instance</a>
+        must be running and reachable to Quasarr!</span><br><br>
+        <label for="url">FlareSolverr URL</label>
+        <input type="text" id="url" name="url" placeholder="http://192.168.0.1:8191/v1"><br>
+        '''
+        form_html = f'''
+        <form action="/api/flaresolverr" method="post">
+            {form_content}
+            {render_button("Save", "primary", {"type": "submit"})}
+        </form>
+        '''
+        return render_form("Set FlareSolverr URL", form_html)
+
+    @app.post('/api/flaresolverr')
+    def set_flaresolverr_url():
+        url = request.forms.get('url').strip()
+        config = Config("FlareSolverr")
+
+        if url:
+            try:
+                headers = {"Content-Type": "application/json"}
+                data = {
+                    "cmd": "request.get",
+                    "url": "http://www.google.com/",
+                    "maxTimeout": 30000
+                }
+                response = requests.post(url, headers=headers, json=data, timeout=30)
+                if response.status_code == 200:
+                    config.save("url", url)
+                    print(f'Using Flaresolverr URL: "{url}"')
+                    quasarr.providers.web_server.temp_server_success = True
+                    return render_success("FlareSolverr URL saved successfully!", 5)
+            except requests.RequestException:
+                pass
+
+        # on failure, clear any existing value and notify user
+        config.save("url", "")
+        return render_fail("Could not reach FlareSolverr at that URL (expected HTTP 200).")
+
+    info(
+        '"flaresolverr" URL is required for proper operation. '
+        f'Starting web server for config at: "{shared_state.values["internal_address"]}".'
+    )
+    info("Please enter your FlareSolverr URL now.")
+    return Server(app, listen='0.0.0.0', port=shared_state.values['port']).serve_temporarily()
+
+
 def jdownloader_config(shared_state):
     app = Bottle()
 
     @app.get('/')
-    def hostname_form():
+    def jd_form():
         verify_form_html = f'''
         <span>If required register account at: <a href="https://my.jdownloader.org/login.html#register">
-        my.jdownloader.org</a>!</span><br><br>
-        
+        my.jdownloader.org</a>!</span><br>
+
+        <p><strong>JDownloader must be running and connected to My JDownloader!</strong></p><br>
+
         <form id="verifyForm" action="/api/verify_jdownloader" method="post">
             <label for="user">E-Mail</label>
             <input type="text" id="user" name="user" placeholder="user@example.org" autocorrect="off"><br>
@@ -193,9 +357,9 @@ def jdownloader_config(shared_state):
                            "secondary",
                            {"id": "verifyButton", "type": "button", "onclick": "verifyCredentials()"})}
         </form>
-        
+
         <p>Some JDownloader settings will be enforced by Quasarr on startup.</p>
-        
+
         <form action="/api/store_jdownloader" method="post" id="deviceForm" style="display: none;">
             <input type="hidden" id="hiddenUser" name="user">
             <input type="hidden" id="hiddenPass" name="pass">
@@ -203,6 +367,7 @@ def jdownloader_config(shared_state):
             <select id="device" name="device"></select><br>
             {render_button("Save", "primary", {"type": "submit"})}
         </form>
+        <p><strong>Saving may take a while!</strong></p><br>
         '''
 
         verify_script = '''

quasarr-1.20.4.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: quasarr
+Version: 1.20.4
+Summary: Quasarr connects JDownloader with Radarr, Sonarr and LazyLibrarian. It also decrypts links protected by CAPTCHAs.
+Home-page: https://github.com/rix1337/Quasarr
+Author: rix1337
+Author-email: 
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.14.2
+Requires-Dist: bottle>=0.13.4
+Requires-Dist: dukpy>=0.5.0
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: pycryptodomex>=3.23.0
+Requires-Dist: requests>=2.32.5
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+#   
+
+<img src="https://raw.githubusercontent.com/rix1337/Quasarr/main/Quasarr.png" data-canonical-src="https://raw.githubusercontent.com/rix1337/Quasarr/main/Quasarr.png" width="64" height="64" />
+
+Quasarr connects JDownloader with Radarr, Sonarr and LazyLibrarian. It also decrypts links protected by CAPTCHAs.
+
+[![PyPI version](https://badge.fury.io/py/quasarr.svg)](https://badge.fury.io/py/quasarr)
+[![Discord](https://img.shields.io/discord/1075348594225315891)](https://discord.gg/eM4zA2wWQb)
+[![GitHub Sponsorship](https://img.shields.io/badge/support-me-red.svg)](https://github.com/users/rix1337/sponsorship)
+
+Quasarr pretends to be both `Newznab Indexer` and `SABnzbd client`. Therefore, do not try to use it with real usenet
+indexers or download clients. It simply does not know what NZB or torrent files are.
+
+Quasarr includes a solution to quickly and easily decrypt protected links.
+[Active monthly Sponsors get access to SponsorsHelper to do so automatically.](https://github.com/rix1337/Quasarr?tab=readme-ov-file#sponsorshelper)
+Alternatively, follow the link from the console output (or discord notification) to solve CAPTCHAs manually.
+Quasarr will confidently handle the rest.
+
+# Instructions
+1. Set up and run [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) 3.4.4 or later.
+2. Set up and run [JDownloader 2](https://jdownloader.org/download/index).
+3. Follow the next steps.
+
+---
+
+## FlareSolverr
+1. Ensure your running FlareSolverr is reachable by Quasarr.
+2. Provide your FlareSolverr URL to Quasarr during the setup process.
+3. The full URL must include the version path, e.g., `http://192.168.1.1:8191/v1`.
+
+---
+
+## Quasarr
+
+Tell Quasarr which sites to search for releases. It requires at least one valid source to start up.
+
+> - By default, Quasarr does **not** know which sites to scrape for download links.  
+> - The setup will guide you through the process of providing valid hostnames for Quasarr to scrape.  
+> - Do **not** ask for help here if you do not know which hostnames to use. Picking them is solely your responsibility.  
+> - You may check sites like [Pastebin](https://pastebin.com/search?q=hostnames+quasarr) for user‑submitted suggestions.
+
+---
+
+## JDownloader
+
+1. Ensure your running JDownloader is connected to the My JDownloader service.  
+2. Provide your [My‑JDownloader‑Credentials](https://my.jdownloader.org) to Quasarr during the setup process.
+
+> - Consider setting up a fresh JDownloader before you begin.  
+> - JDownloader must be running and available to Quasarr.  
+> - Quasarr will modify JDownloader’s settings so downloads can be handled by Radarr/Sonarr/LazyLibrarian.  
+> - If using Docker, ensure that JDownloader’s download path is available to Radarr/Sonarr/LazyLibrarian with **exactly the same** internal and external path mapping (matching only the external path is not enough).
+
+---
+
+## Radarr / Sonarr
+
+Set up Quasarr as a **Newznab Indexer** and **SABnzbd Download Client**:
+
+1. **URL**: Use the `URL` from the **API Information** section of the console output (or copy it from the Quasarr web UI).  
+2. **API Key**: Use the `API Key` from the **API Information** section of the console output (or copy it from the Quasarr web UI).  
+3. Leave all other settings at their defaults.
+
+> **Important notice for Sonarr**  
+> - Ensure all shows (including anime) are set to the **Standard** series type.  
+> - Quasarr will never find releases for shows set to **Anime / Absolute**.
+
+---
+
+## LazyLibrarian
+
+> **Important notice**
+> - This feature is experimental and may not work as expected.
+> - Quasarr cannot help you with metadata issues, missing covers, or other LazyLibrarian problems.
+> - Please report issues when one of your hostnames yields results through their website, but not in LazyLibrarian.
+
+Set up Quasarr as a **SABnzbd+ Downloader**
+
+1. **SABnzbd URL/Port**: Use port and host parts from `URL` found in the **API Information** section of the console output (or copy it from the Quasarr web UI).  
+2. **SABnzbd API Key**: Use the `API Key` from the **API Information** section of the console output (or copy it from the Quasarr web UI).  
+3. **SABnzbd Category**: Use `docs` to ensure LazyLibrarian does not interfere with Radarr/Sonarr.  
+4. Press `Test SABnzbd` to verify the connection, then `Save changes`.
+
+Set up Quasarr as a **Newznab Provider**:
+1. **Newznab URL**: Use the `URL` from the **API Information** section of the console output (or copy it from the Quasarr web UI).
+2. **Newznab API** Use the `API Key` from the **API Information** section of the console output (or copy it from the Quasarr web UI).
+3. Press `Test` to verify the connection, then `Save changes`.
+
+Fix the `Importing` settings:
+1. Check `Enable OpenLibrary api for book/author information`
+2. Select `OpenLibrary` below `Primary Information Source`
+2. Under `Import languages` add `, Unknown` (and for German users: `, de, ger, de-DE`).
+
+Fix the `Processing` settings:
+1. Under `Folders` add the full Quasarr download path, typically `/downloads/Quasarr/`
+2. If you do not do this,  processing after the download will fail.
+
+
+
+---
+
+## Advanced Settings
+
+To restrict results to a specific mirror, add the mirror name to the Newznab/indexer URL.  
+> **Example:** Appending `/api/dropbox/` will only return releases where `dropbox` is explicitly mentioned in a link.  
+> **Caution:** If a mirror is not available at a hostname, the release will be ignored or the download will fail. Use this option carefully.
+
+To see download status information in Radarr/Sonarr
+1. Open `Activity` → `Queue` → `Options`
+2. Enable `Release Title`
+
+# Docker
+
+It is highly recommended to run the latest docker image with all optional variables set.
+
+```
+docker run -d \
+  --name="Quasarr" \
+  -p port:8080 \
+  -v /path/to/config/:/config:rw \
+  -e 'INTERNAL_ADDRESS'='http://192.168.0.1:8080' \
+  -e 'EXTERNAL_ADDRESS'='https://foo.bar/' \
+  -e 'DISCORD'='https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMN' \
+  -e 'HOSTNAMES'='https://pastebin.com/raw/eX4Mpl3'
+  -e 'SILENT'='True' \
+  -e 'DEBUG'='' \
+  ghcr.io/rix1337/quasarr:latest
+  ```
+
+* `INTERNAL_ADDRESS` is required so Radarr/Sonarr/LazyLibrarian can reach Quasarr. **Must** include port!
+* `EXTERNAL_ADDRESS` is optional and helpful if using a reverse proxy. Always protect external access with basic auth!
+* `DISCORD` is optional and must be a valid Discord webhook URL.
+* `HOSTNAMES` is optional and allows skipping the manual hostname step during setup.
+    * Must be a publicly available `HTTP` or `HTTPs` link
+    * Must be a raw `.ini` / text file (not HTML or JSON)
+    * Must contain at least one valid Hostname per line `ab = xyz`
+* `SILENT` is optional and silences all discord notifications except for error messages from SponsorsHelper if `True`.
+* `DEBUG` is optional and enables debug logging if `True`.
+
+# Manual setup
+
+Use this only in case you can't run the docker image.
+
+`pip install quasarr`
+
+* Requires Python 3.12 or later
+* Requires [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr)
+* Requires [JDownloader 2](https://jdownloader.org/download/index) with [My JDownloader](https://my.jdownloader.org/)
+
+```
+  --port=8080
+  --discord=https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMN
+  --external_address=https://foo.bar/
+  --hostnames=https://pastebin.com/raw/eX4Mpl3
+  ```
+
+* `--discord` see `DISCORD`docker variable
+* `--external_address` see `EXTERNAL_ADDRESS`docker variable
+* `--hostnames` see `HOSTNAMES`docker variable
+
+# Philosophy
+
+Complexity is the killer of small projects like this one. It must be fought at all cost!
+
+We will not waste precious time on features that will slow future development cycles down.
+Most feature requests can be satisfied by:
+
+- Existing settings in Radarr/Sonarr/LazyLibrarian
+- Existing settings in JDownloader
+- Existing tools from the *arr ecosystem that integrate directly with Radarr/Sonarr/LazyLibrarian
+
+# Roadmap
+
+- Assume there are zero known
+  issues [unless you find one or more open issues in this repository](https://github.com/rix1337/Quasarr/issues).
+- Still having an issue? Provide a detailed report [here](https://github.com/rix1337/Quasarr/issues/new/choose)!
+- There are no hostname integrations in active development unless you see an open pull request
+  [here](https://github.com/rix1337/Quasarr/pulls).
+- Pull requests are welcome. Especially for popular hostnames.
+    - Always reach out on Discord before starting work on a new feature to prevent waste of time.
+    - Please follow the existing code style and project structure.
+    - Anti-bot measures must be circumvented fully by Quasarr. Thus you will need to provide a working solution for new
+      CAPTCHA types by integrating it in the Quasarr Web UI.
+    - Please provide proof of functionality (screenshots/examples) when submitting your pull request.
+
+# SponsorsHelper
+
+<img src="https://imgur.com/iHBqLwT.png" width="64" height="64" />
+
+SponsorsHelper is a Docker image that solves CAPTCHAs and decrypts links for Quasarr.  
+Image access is limited to [active monthly GitHub sponsors](https://github.com/users/rix1337/sponsorship).
+
+[![Github Sponsorship](https://img.shields.io/badge/support-me-red.svg)](https://github.com/users/rix1337/sponsorship)
+
+---
+
+## 🔑 GitHub Token Setup
+
+1. Start your [sponsorship](https://github.com/users/rix1337/sponsorship) first.
+2. Open [GitHub Classic Token Settings](https://github.com/settings/tokens/new?type=classic)
+3. Name it (e.g., `SponsorsHelper`) and choose unlimited expiration  
+4. Enable these scopes:
+   - `read:packages`
+   - `read:user`
+   - `read:org`
+5. Click **Generate token** and copy it for the next steps
+
+---
+
+## 🐋 Docker Login
+
+```bash
+echo "GITHUB_TOKEN" | docker login ghcr.io -u USERNAME --password-stdin
+````
+
+* `USERNAME` → your GitHub username
+* `GITHUB_TOKEN` → the token you just created
+
+---
+
+⚠️ **Before logging in, the image will not download.**
+
+---
+
+## ▶️ Run SponsorsHelper
+
+```bash
+docker run -d \
+  --name='SponsorsHelper' \
+  -e 'QUASARR_URL'='http://192.168.0.1:8080' \
+  -e 'DEATHBYCAPTCHA_TOKEN'='2FMum5zuDBxMmbXDIsADnllEFl73bomydIpzo7...' \
+  -e 'GITHUB_TOKEN'='ghp_123.....456789' \
+  -e 'FLARESOLVERR_URL'='http://10.10.0.1:8191/v1' \
+  -e 'NX_USER'='your_nx_username' \
+  -e 'NX_PASS'='your_nx_password' \
+  -e 'JUNKIES_USER'='your_junkies_username' \
+  -e 'JUNKIES_PASS'='your_junkies_password' \
+  -e 'JUNKIES_HOSTER'='your_desired_hoster' \
+  ghcr.io/rix1337-sponsors/docker/helper:latest
+```
+
+### Required Parameters
+
+* `QUASARR_URL` → Local URL of Quasarr
+* `DEATHBYCAPTCHA_TOKEN` → [DeathByCaptcha](https://deathbycaptcha.com/register?refid=6184288242b) account token
+* `GITHUB_TOKEN` → Classic GitHub PAT with the scopes listed above
+* `FLARESOLVERR_URL` → Local URL of [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) - required!
+* `NX_USER` / `NX_PASS` → NX account credentials
+* `JUNKIES_USER` / `JUNKIES_PASS` → Junkies account credentials
+* `JUNKIES_HOSTER` → Preferred hoster for Junkies links
+---
+
+⚠️ **Without a valid GitHub token linked to an active sponsorship, the image will not run.**
+
+---
+
+# Development Setup for Pull Requests
+
+To test your changes before submitting a pull request:
+
+**Run Quasarr with the `--internal_address` parameter:**
+
+```bash
+python Quasarr.py --internal_address=http://<host-ip>:<port>
+```
+
+Replace `<host-ip>` and `<port>` with the scheme, IP, and port of your host machine.
+The `--internal_address` parameter is **mandatory**.
+
+**Start the required services using the `dev-services-compose.yml` file:**
+
+```bash
+CONFIG_VOLUMES=/path/to/config docker-compose -f docker/dev-services-compose.yml up
+```
+
+Replace `/path/to/config` with your desired configuration location.
+The `CONFIG_VOLUMES` environment variable is **mandatory**.