From 3278a24931ecdd36e1cd7da132c7ca567eecefac Mon Sep 17 00:00:00 2001 From: Flaminel Date: Thu, 26 Jun 2025 20:00:22 +0300 Subject: [PATCH] changed docs #3 --- .../core/services/documentation.service.ts | 4 +- .../configuration/content-blocker/index.mdx | 12 +- .../configuration/download-cleaner/index.mdx | 32 +-- .../download-client/1_general.mdx | 11 - .../configuration/download-client/2_qbit.mdx | 7 - .../download-client/3_deluge.mdx | 7 - .../download-client/4_transmission.mdx | 7 - .../download-client/_category_.json | 8 - .../configuration/download-client/index.mdx | 213 ++---------------- docs/docs/configuration/general/index.mdx | 16 +- .../configuration/notifications/index.mdx | 8 +- .../configuration/queue-cleaner/index.mdx | 46 ++-- docs/docs/{1_cleanuperr.mdx => index.mdx} | 0 docs/docs/setup-scenarios/1_qbit-built-in.mdx | 2 +- .../2_cleanuperr-blocklist.mdx | 4 +- .../docs/setup-scenarios/3_failed-imports.mdx | 13 +- 16 files changed, 92 insertions(+), 298 deletions(-) delete mode 100644 docs/docs/configuration/download-client/1_general.mdx delete mode 100644 docs/docs/configuration/download-client/2_qbit.mdx delete mode 100644 docs/docs/configuration/download-client/3_deluge.mdx delete mode 100644 docs/docs/configuration/download-client/4_transmission.mdx delete mode 100644 docs/docs/configuration/download-client/_category_.json rename docs/docs/{1_cleanuperr.mdx => index.mdx} (100%) diff --git a/code/frontend/src/app/core/services/documentation.service.ts b/code/frontend/src/app/core/services/documentation.service.ts index b5569b9b..81706361 100644 --- a/code/frontend/src/app/core/services/documentation.service.ts +++ b/code/frontend/src/app/core/services/documentation.service.ts @@ -87,8 +87,8 @@ export class DocumentationService { 'type': 'client-type', 'host': 'client-host', 'urlBase': 'url-base-path', - 'username': 'authentication-username', - 'password': 'authentication-password' + 'username': 'username', + 'password': 'password' }, 'notifications': { 'notifiarr.apiKey': 'notifiarr-api-key', diff --git a/docs/docs/configuration/content-blocker/index.mdx b/docs/docs/configuration/content-blocker/index.mdx index 0ed0d5c0..564cdd8c 100644 --- a/docs/docs/configuration/content-blocker/index.mdx +++ b/docs/docs/configuration/content-blocker/index.mdx @@ -2,13 +2,15 @@ sidebar_position: 2 --- +import { Important, Warning } from '@site/src/components/Admonition'; + # Content Blocker The Content Blocker automatically blocks or removes downloads from your download client based on configurable blocklists. This helps prevent unwanted content from being downloaded and manages content filtering across your *arr applications. -:::important -These settings need a download client to be configured. -::: + + These settings need a download client to be configured. + ### Enable Content Blocker {#enable-content-blocker} @@ -45,9 +47,9 @@ When enabled, private torrents will be skipped from being processed during conte When enabled, private torrents that match blocklist criteria will be deleted from the download client. Use with extreme caution as this permanently removes the download. -:::warning + Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. -::: +
diff --git a/docs/docs/configuration/download-cleaner/index.mdx b/docs/docs/configuration/download-cleaner/index.mdx index 328528bc..e72f2219 100644 --- a/docs/docs/configuration/download-cleaner/index.mdx +++ b/docs/docs/configuration/download-cleaner/index.mdx @@ -2,13 +2,15 @@ sidebar_position: 4 --- +import { Note, Important, Warning } from '@site/src/components/Admonition'; + # Download Cleaner The Download Cleaner automatically removes downloads from your download client after they have finished seeding according to configurable rules. This helps manage disk space and maintain optimal seeding ratios. -:::important -These settings need a download client to be configured. -::: + + These settings need a download client to be configured. + ### Enable Download Cleaner {#enable-download-cleaner} @@ -43,9 +45,9 @@ Settings that control how downloads are cleaned after they finish downloading. When enabled, private torrents will be deleted from the download client when they meet the cleanup criteria. Use with caution as this permanently removes the download. -:::warning -Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. -::: + + Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. +
@@ -53,13 +55,13 @@ Setting this to true means private torrents will be permanently deleted, potenti Categories define the cleanup rules for different types of downloads. Each category specifies when downloads should be removed based on ratio and time limits. -:::note -A download is cleaned when both `Max Ratio` and `Min Seed Time` are reached, OR when `Max Seed Time` is reached regardless of ratio. -::: + + A download is cleaned when both `Max Ratio` and `Min Seed Time` are reached, OR when `Max Seed Time` is reached regardless of ratio. + -:::important -Both Max Ratio and Max Seed Time cannot be disabled (-1) at the same time. At least one cleanup condition must be configured. -::: + + Both Max Ratio and Max Seed Time cannot be disabled (-1) at the same time. At least one cleanup condition must be configured. + #### Category Name {#category-name} @@ -98,9 +100,9 @@ Settings for managing downloads that no longer have hardlinks to media files (in Enable management of downloads that have no hardlinks remaining. This helps identify downloads that are no longer needed by your *arr applications. -:::important -If you are using Docker, make sure to mount the downloads directory the same way it is mounted for the download client. If your download client's download directory is `/downloads`, it should be the same for Cleanuparr. -::: + + If you are using Docker, make sure to mount the downloads directory the same way it is mounted for the download client. If your download client's download directory is `/downloads`, it should be the same for Cleanuparr. +
diff --git a/docs/docs/configuration/download-client/1_general.mdx b/docs/docs/configuration/download-client/1_general.mdx deleted file mode 100644 index b30261c2..00000000 --- a/docs/docs/configuration/download-client/1_general.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 1 ---- - -import DownloadClientSettings from '@site/src/components/configuration/download-client/DownloadClientSettings'; - -# General settings - -These settings control how Cleanuparr interacts with your download client. - - \ No newline at end of file diff --git a/docs/docs/configuration/download-client/2_qbit.mdx b/docs/docs/configuration/download-client/2_qbit.mdx deleted file mode 100644 index 9ecf2d82..00000000 --- a/docs/docs/configuration/download-client/2_qbit.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import QBittorrentSettings from '@site/src/components/configuration/download-client/QBittorrentSettings'; - -# qBittorrent settings - -Settings used to access your qBittorrent instance. - - \ No newline at end of file diff --git a/docs/docs/configuration/download-client/3_deluge.mdx b/docs/docs/configuration/download-client/3_deluge.mdx deleted file mode 100644 index ed4258cc..00000000 --- a/docs/docs/configuration/download-client/3_deluge.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import DelugeSettings from '@site/src/components/configuration/download-client/DelugeSettings'; - -# Deluge settings - -Settings used to access your Deluge instance. - - \ No newline at end of file diff --git a/docs/docs/configuration/download-client/4_transmission.mdx b/docs/docs/configuration/download-client/4_transmission.mdx deleted file mode 100644 index f84200cf..00000000 --- a/docs/docs/configuration/download-client/4_transmission.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import TransmissionSettings from '@site/src/components/configuration/download-client/TransmissionSettings'; - -# Transmission settings - -Settings used to access your Transmission instance. - - \ No newline at end of file diff --git a/docs/docs/configuration/download-client/_category_.json b/docs/docs/configuration/download-client/_category_.json deleted file mode 100644 index 4b42dcc6..00000000 --- a/docs/docs/configuration/download-client/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Download Client", - "position": 6, - "link": { - "type": "generated-index", - "description": "Configure the download client settings for Cleanuparr." - } -} \ No newline at end of file diff --git a/docs/docs/configuration/download-client/index.mdx b/docs/docs/configuration/download-client/index.mdx index 08e0160f..29b8b0b6 100644 --- a/docs/docs/configuration/download-client/index.mdx +++ b/docs/docs/configuration/download-client/index.mdx @@ -1,93 +1,39 @@ -# Download Client Configuration +--- +sidebar_position: 6 +--- + +# Download Client Configure download client connections for torrents and usenet. Cleanuparr supports qBittorrent, Deluge, and Transmission download clients. -## Client Management - -Download clients are managed as individual instances. You can add multiple clients of the same or different types to handle various download workflows. - -### Supported Client Types - -- **qBittorrent**: Most popular, feature-rich torrent client -- **Deluge**: Lightweight, daemon-based torrent client -- **Transmission**: Simple, cross-platform torrent client - -## Client Configuration - ### Enable Download Client {#enable-download-client} -**Field**: `enabled` -**Type**: Boolean -**Default**: `true` - Controls whether this download client instance is active and will be used by Cleanuparr for operations. **When Enabled**: -- Client will be available for queue operations -- Health checks will monitor this client -- All configured features will apply to this client +- Client will be available for slow, stalled and private tracker operations. +- Health checks will monitor this client. **When Disabled**: -- Client will be ignored by all Cleanuparr operations -- No health checks will be performed -- Useful for temporarily disabling without deleting configuration +- Client will be ignored by all Cleanuparr operations. +- No health checks will be performed. -**Best Practice**: Disable clients during maintenance rather than deleting their configuration. +
### Client Name {#client-name} -**Field**: `name` -**Type**: String -**Required**: Yes - A descriptive name to identify this download client instance in the Cleanuparr interface. -**Examples**: -- `qBittorrent Main` -- `Seedbox qBittorrent` -- `Local Deluge` -- `4K Movies Transmission` - -**Best Practices**: -- Use descriptive names that indicate purpose or location -- Include client type if managing multiple types -- Keep names short but meaningful for easy identification +
### Client Type {#client-type} -**Field**: `type` -**Type**: Dropdown Selection -**Required**: Yes -**Options**: qBittorrent, Deluge, Transmission - Specifies which download client software this configuration connects to. -**qBittorrent**: -- Most feature-rich option -- Web UI on port 8080 by default -- Supports categories, tags, and ratios -- Best compatibility with Cleanuparr features - -**Deluge**: -- Lightweight daemon-based client -- Web UI on port 8112 by default -- Good for resource-constrained systems -- Supports plugins and advanced configurations - -**Transmission**: -- Simple, cross-platform client -- Web UI on port 9091 by default -- Minimal resource usage -- Basic but reliable functionality - -**Important**: Client type cannot be changed after creation. Delete and recreate if needed. +
### Client Host {#client-host} -**Field**: `host` -**Type**: URL -**Required**: Yes - The complete URL to access your download client's web interface. **Format**: `protocol://hostname:port` @@ -98,143 +44,26 @@ The complete URL to access your download client's web interface. - `http://192.168.1.100:8112` (local network Deluge) - `http://transmission.lan:9091` (local Transmission) -**Protocol Requirements**: -- Must use `http://` or `https://` -- HTTPS recommended for remote connections -- HTTP acceptable for local/trusted networks - -**Port Guidelines**: -- qBittorrent: Usually 8080 -- Deluge: Usually 8112 -- Transmission: Usually 9091 -- Check your client's web UI settings for the actual port - -**Common Issues**: -- Ensure firewall allows the port -- Check that web UI is enabled in client settings -- Verify URL is accessible from Cleanuparr's location +
### URL Base Path {#url-base-path} -**Field**: `urlBase` -**Type**: String (Optional) - URL path prefix if your download client runs behind a reverse proxy with a subpath. **When to Use**: -- Client accessed via reverse proxy (Nginx, Apache, Traefik) -- Client uses non-root URL path -- Multiple services share same domain/port +- Client accessed via reverse proxy (Nginx, Apache, Traefik). +- Client uses non-root URL path. +- Multiple services share same domain/port. **Examples**: -- `/qbittorrent` → Full URL: `http://domain.com/qbittorrent` -- `/downloads/deluge` → Full URL: `http://domain.com/downloads/deluge` -- `/transmission` → Full URL: `http://domain.com/transmission` +- `qbittorrent` → Full URL: `http://domain.com/qbittorrent` +- `downloads/deluge` → Full URL: `http://domain.com/downloads/deluge` +- `transmission` → Full URL: `http://domain.com/transmission` -**Format Rules**: -- Start with forward slash (`/`) -- No trailing slash -- Use lowercase, hyphens for readability -- Match your reverse proxy configuration exactly - -**Configuration Notes**: -- Leave empty if accessing client directly (no proxy) -- Must match reverse proxy path configuration -- Test URL manually before saving - -## Authentication - -### Authentication Username {#authentication-username} - -**Field**: `username` -**Type**: String (Optional) +### Username {#username} Username for download client authentication if required. -**When Required**: -- Client has authentication enabled -- Accessing client over network/internet -- Multiple users share same client - -**When Not Needed**: -- Client runs locally without authentication -- Client configured for no-auth local access -- Using alternative authentication methods - -**Security Considerations**: -- Use dedicated user account for Cleanuparr -- Limit permissions to necessary operations only -- Regular client may not need admin privileges - -### Authentication Password {#authentication-password} - -**Field**: `password` -**Type**: Password (Optional) +### Password {#password} Password for download client authentication. - -**Security Best Practices**: -- Use strong, unique passwords -- Consider client-specific credentials -- Store securely and rotate regularly -- Use HTTPS when sending over network - -**Client-Specific Notes**: -- **qBittorrent**: Web UI username/password -- **Deluge**: Web UI password (username often not required) -- **Transmission**: HTTP authentication if enabled - -## Connection Testing - -After configuring a download client, Cleanuparr will: - -1. **Test Connection**: Verify URL accessibility -2. **Authenticate**: Log in using provided credentials -3. **API Check**: Confirm client API compatibility -4. **Health Monitor**: Ongoing connection monitoring - -**Troubleshooting Connection Issues**: - -- **Connection Failed**: Check host URL, port, firewall -- **Authentication Failed**: Verify username/password -- **API Error**: Ensure client version compatibility -- **Timeout**: Check network latency, increase timeout settings - -## Multiple Client Setup - -You can configure multiple download clients for different purposes: - -**Use Cases**: -- **Primary/Backup**: Main client with fallback option -- **Content Separation**: Movies vs TV shows vs music -- **Performance Tiers**: Fast SSD vs slower storage -- **Geographic Distribution**: Multiple seedbox locations - -**Configuration Strategy**: -- Use descriptive names for each client -- Test each client independently -- Monitor performance across all clients -- Configure appropriate settings per client purpose - -## Best Practices - -### Performance Optimization - -- **Local Clients**: Use HTTP for speed -- **Remote Clients**: Use HTTPS for security -- **Network Clients**: Consider connection pooling -- **Multiple Clients**: Balance load appropriately - -### Security Considerations - -- **Credentials**: Use least-privilege accounts -- **Network**: Secure client web interfaces -- **Access**: Limit administrative functions -- **Monitoring**: Enable logging for security events - -### Maintenance Tips - -- **Regular Testing**: Verify connections periodically -- **Update Coordination**: Keep client versions compatible -- **Backup Configuration**: Export settings before changes -- **Documentation**: Maintain client setup notes \ No newline at end of file diff --git a/docs/docs/configuration/general/index.mdx b/docs/docs/configuration/general/index.mdx index c540df49..4a73130e 100644 --- a/docs/docs/configuration/general/index.mdx +++ b/docs/docs/configuration/general/index.mdx @@ -2,7 +2,9 @@ sidebar_position: 1 --- -# General Configuration +import { Note, Warning } from '@site/src/components/Admonition'; + +# General General configuration settings that apply to the entire Cleanuparr application. @@ -51,9 +53,9 @@ Controls whether to validate SSL certificates for HTTPS connections. Set to "Dis Enables searching for replacements after a download has been removed from an *arr application. -:::note -If you are using [Huntarr](https://github.com/plexguide/Huntarr.io), you may want to set disable this setting to let Huntarr handle the searching. -::: + + If you are using [Huntarr](https://github.com/plexguide/Huntarr.io), you may want to set disable this setting to let Huntarr handle the searching. +
@@ -61,9 +63,9 @@ If you are using [Huntarr](https://github.com/plexguide/Huntarr.io), you may wan If searching for replacements is enabled, this setting will delay the searches by the specified number of seconds. This is useful to avoid overwhelming the indexer with too many requests at once. -:::warning -A lower value or `0` will result in faster searches, but may cause issues such as being rate limited or banned by the indexer. -::: + + A lower value or `0` will result in faster searches, but may cause issues such as being rate limited or banned by the indexer. +
diff --git a/docs/docs/configuration/notifications/index.mdx b/docs/docs/configuration/notifications/index.mdx index 7877efc9..1085779b 100644 --- a/docs/docs/configuration/notifications/index.mdx +++ b/docs/docs/configuration/notifications/index.mdx @@ -1,7 +1,9 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- +import { Important } from '@site/src/components/Admonition'; + # Notifications Configure notification services to receive alerts about Cleanuparr operations. @@ -16,9 +18,9 @@ Notifiarr is a notification service that can send alerts to Discord. Your Notifiarr API key for authentication. This key is obtained from your Notifiarr dashboard. -:::important + Requires Notifiarr's [Passthrough](https://notifiarr.wiki/pages/integrations/passthrough/) integration to work. -::: +
diff --git a/docs/docs/configuration/queue-cleaner/index.mdx b/docs/docs/configuration/queue-cleaner/index.mdx index c1d964be..64068817 100644 --- a/docs/docs/configuration/queue-cleaner/index.mdx +++ b/docs/docs/configuration/queue-cleaner/index.mdx @@ -2,7 +2,9 @@ sidebar_position: 3 --- -# Queue Cleaner Configuration +import { Important, Warning } from '@site/src/components/Admonition'; + +# Queue Cleaner The Queue Cleaner monitors your download client's queue and automatically removes downloads based on configurable criteria. This helps keep your queue clean and prevents problematic downloads from consuming resources. @@ -43,9 +45,9 @@ Number of strikes before a failed import download is removed from the queue. Set When enabled, private torrents will be skipped during failed import cleaning. This is useful if you want to preserve private tracker content even when imports fail. -:::important -This setting needs a download client to be configured. -::: + + This setting needs a download client to be configured. +
@@ -53,13 +55,13 @@ This setting needs a download client to be configured. When enabled, private torrents that reach the maximum strikes will be deleted from the download client. Use with caution as this will permanently remove the download. -:::warning -Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. -::: + + Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. + -:::important -This setting needs a download client to be configured. -::: + + This setting needs a download client to be configured. +
@@ -77,9 +79,9 @@ Failed imports containing these patterns in their name will be skipped during cl Stalled downloads are those that have stopped downloading and show no progress. -:::important -These settings need a download client to be configured. -::: + + These settings need a download client to be configured. + ### Stalled Max Strikes {#stalled-max-strikes} @@ -103,9 +105,9 @@ When enabled, private torrents will be skipped during stalled download cleaning. When enabled, private torrents that reach the maximum strikes will be deleted from the download client. -:::warning -Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. -::: + + Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. +
@@ -119,9 +121,9 @@ Number of strikes before a download stuck in "Downloading Metadata" state is rem Slow downloads are those downloading below a specified speed threshold. -:::important -These settings need a download client to be configured. -::: + + These settings need a download client to be configured. + ### Slow Max Strikes {#slow-max-strikes} @@ -145,9 +147,9 @@ When enabled, private torrents will be skipped during slow download cleaning. When enabled, private torrents that reach the maximum strikes will be deleted from the download client. -:::warning -Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. -::: + + Setting this to true means private torrents will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met. +
diff --git a/docs/docs/1_cleanuperr.mdx b/docs/docs/index.mdx similarity index 100% rename from docs/docs/1_cleanuperr.mdx rename to docs/docs/index.mdx diff --git a/docs/docs/setup-scenarios/1_qbit-built-in.mdx b/docs/docs/setup-scenarios/1_qbit-built-in.mdx index 1f20c5fb..ba00954f 100644 --- a/docs/docs/setup-scenarios/1_qbit-built-in.mdx +++ b/docs/docs/setup-scenarios/1_qbit-built-in.mdx @@ -7,7 +7,7 @@ import { Note } from '@site/src/components/Admonition'; - [permissive blacklist](https://raw.githubusercontent.com/Cleanuparr/Cleanuparr/refs/heads/main/blacklist_permissive), or - create your own 2. qBittorrent will block files from being downloaded. In the case of malicious content, **nothing is downloaded and the torrent is marked as complete**. -3. Start **Cleanuparr** with `QUEUECLEANER__ENABLED` set to `true`. +3. Use **Cleanuparr** with `Queue Cleaner` enabled. 4. The **Queue Cleaner** will perform a cleanup process as described in the [How it works](/docs/how_it_works) section. diff --git a/docs/docs/setup-scenarios/2_cleanuperr-blocklist.mdx b/docs/docs/setup-scenarios/2_cleanuperr-blocklist.mdx index 15ef476d..2ac60337 100644 --- a/docs/docs/setup-scenarios/2_cleanuperr-blocklist.mdx +++ b/docs/docs/setup-scenarios/2_cleanuperr-blocklist.mdx @@ -2,8 +2,8 @@ import { Note } from '@site/src/components/Admonition'; # Using Cleanuparr's blocklist feature (torrent) -1. Set both `QUEUECLEANER__ENABLED` and `CONTENTBLOCKER__ENABLED` to `true` in your environment variables. -2. Configure and enable either a **blacklist** or a **whitelist** as described in the [Arr settings](/docs/category/arrs-settings) section. +1. Enable both `Queue Cleaner`. +2. Enable `Content Blocker` and configure either a **blacklist** or a **whitelist** for each *arr. 3. Once configured, Cleanuparr will perform the following tasks: - Execute the **Content Blocker** job, as explained in the [How it works](/docs/how_it_works) section. - Execute the **Queue Cleaner** job, as explained in the [How it works](/docs/how_it_works) section. diff --git a/docs/docs/setup-scenarios/3_failed-imports.mdx b/docs/docs/setup-scenarios/3_failed-imports.mdx index 6171df00..097687b4 100644 --- a/docs/docs/setup-scenarios/3_failed-imports.mdx +++ b/docs/docs/setup-scenarios/3_failed-imports.mdx @@ -2,15 +2,10 @@ import { Important } from '@site/src/components/Admonition'; # Using Cleanuparr just for failed imports (torrent and usenet) -1. Set `QUEUECLEANER__ENABLED` to `true`. -2. Set `QUEUECLEANER__IMPORT_FAILED_MAX_STRIKES` to a desired value. -3. Optionally set failed import message patterns to ignore using `QUEUECLEANER__IMPORT_FAILED_IGNORE_PATTERNS__`. -4. Set `DOWNLOAD_CLIENT` to `none`(works only for usenet) or `disabled` (works for both usenet and torrent). +1. Enable the `Queue Cleaner`. +2. Set the `Failed Imports Max Strikes` to a desired value. +3. Optionally set failed import message patterns to ignore potentially valid items from being processed. - When `DOWNLOAD_CLIENT=disabled`, no other action involving a download client would work (e.g. content blocking, removing stalled downloads, excluding private trackers). - - When the download client is set to `disabled`, the queue cleaner will be able to remove items that are failed to be imported even if there is no download client configured. This means that all downloads, including private ones, will be completely removed. - - Setting `DOWNLOAD_CLIENT=disabled` means you don't care about seeding, ratio, H&R and potentially losing your private tracker account. + When no download client is configured, no other action involving a download client would work (e.g. content blocking, removing stalled downloads or excluding private trackers). \ No newline at end of file