Master Guide To Deploying A High-Performance Arr Stack In CasaOS

Automating a media library within CasaOS requires the strategic containerization of Sonarr, Radarr, and Prowlarr using a unified Docker volume architecture. By aligning User IDs and persistent storage paths across the stack, users achieve atomic file moves and instantaneous library updates, maintaining a benchmark of zero-latency post-processing.

Infrastructure Prerequisites and Media Directory Planning

Before initiating the installation of the Arr suite, the underlying host system must be prepared to handle the concurrent input/output operations of multiple Docker containers. CasaOS, while providing a user-friendly abstraction layer over Docker, relies on the stability of the underlying Linux distribution—typically Debian or Ubuntu. The hardware selection should prioritize a minimum of 4GB of RAM and a multi-core processor to manage the database indexing performed by the Arr services.

A critical failure point for most home lab enthusiasts is fragmented directory structures. To ensure that the Arr stack functions with maximum efficiency, you must establish a single-root directory structure. This avoids the overhead of "copy and delete" operations, allowing the system to use "hardlinks" instead. You should create a main directory labeled /DATA/Media on your primary storage drive. Inside this folder, create subdirectories for movies, tv, and downloads. When these are mapped correctly, moving a completed download to your media library happens instantaneously because the system only updates the file's pointer rather than moving the physical bits across the disk.

The essential preparation checklist includes:

• Physical Hardware: A Raspberry Pi 4 (8GB recommended) or an x86-64 Mini PC with at least two available CPU cores.
• Storage Media: A dedicated SATA or NVMe drive formatted to ext4 or XFS; avoid NTFS or exFAT due to permission mapping limitations in Linux environments.
• Network Stability: A static IP address assigned to the CasaOS host to prevent service disconnection between the containers.
• Administrative Access: Full sudo privileges on the host machine to modify system-level permissions if the Web UI encounters restricted access.
• System Identifiers: Knowledge of the PUID (Process User ID) and PGID (Process Group ID), which are typically 1000 for the primary user in a standard Linux installation.

Step-by-Step Deployment of the Arr Stack Pipeline

Step 1: Establishing the Shared Volume Architecture

The foundation of a functional Arr stack is the volume mapping. In CasaOS, navigate to the Files application and navigate to your main storage partition. Create a folder named Media. Inside this folder, create three distinct sub-folders: torrents, movies, and tv. By placing both the torrents and the final media folders under the same parent directory, you enable the Docker engine to perform atomic moves. This technical configuration is vital because if the download folder and the media library are seen as different volumes, the system will be forced to perform a slow copy-and-paste operation, doubling the disk space usage during the process and increasing wear on your storage media.

Step 2: Deploying Prowlarr for Indexer Management

Prowlarr serves as the central nervous system for your stack, managing your trackers and indexers. In the CasaOS dashboard, click the plus icon to add a custom app. Name the application Prowlarr and set the image to lscr.io/linuxserver/prowlarr:latest. In the port settings, map the host port 9696 to the container port 9696. Under the volume settings, map your local configuration folder, such as /DATA/AppData/prowlarr, to the container path /config. Ensure you add the environment variables PUID and PGID, setting both to 1000.

Pro-Tip: Always use the LinuxServer.io versions of these containers. They are professionally maintained, updated daily, and follow a standardized internal structure that makes cross-app communication much more reliable.

Step 3: Integrating the Download Client

A robust Arr stack requires a reliable downloader like qBittorrent or Transmission. Search for qBittorrent in the CasaOS App Store or install it manually. The most important configuration here is the download path. You must map the host path /DATA/Media/torrents to the container path /downloads. It is a common mistake to map it to /DATA/Media; however, specific sub-folders help the Arr services categorize incoming data. Once installed, log into the download client’s web interface and disable the use of sub-categories if you prefer the Arr services to handle all file organization.

Step 4: Installing Radarr and Sonarr for Content Acquisition

Now you will install the management layers. For Radarr (movies), use the image lscr.io/linuxserver/radarr:latest. Map host port 7878 to container port 7878. For Sonarr (TV shows), use lscr.io/linuxserver/sonarr:latest and map host port 8989 to container port 8989. For both applications, you must map the configuration volumes to their respective AppData folders. Crucially, map the host path /DATA/Media to the container path /data. By using /data as the root within the container, both Radarr and Sonarr will see both the torrents folder and the library folders as part of the same file system, facilitating the hardlinking process mentioned earlier.

Step 5: Interconnecting the Services via API

The final phase of the setup is the digital handshake between services. Open Prowlarr and navigate to the Settings menu, then select Apps. Add Radarr and Sonarr by entering their respective CasaOS IP addresses and the API keys found in the General Settings of the Radarr and Sonarr interfaces. Once linked, any indexer you add to Prowlarr will automatically be pushed to Sonarr and Radarr. Finally, in Radarr and Sonarr, navigate to Download Clients and add your qBittorrent instance using the host IP and the login credentials you established in Step 3.

Warning: Do not use "localhost" or 127.0.0.1 when linking containers in CasaOS. Since each container exists in its own isolated network namespace, "localhost" refers to the container itself, not the host. Use the actual LAN IP of your CasaOS machine (e.g., 192.168.1.50).

Technical Configuration and Port Standards

The following table outlines the standard network and environment specifications required for a stable Arr stack within the CasaOS environment. Adhering to these default ports ensures compatibility with third-party tools like FlareSolverr or Overseerr.

Resolving Common Deployment Failures and Permissions Issues

Even with a perfect installation, environmental factors can cause the Arr stack to malfunction. Most issues stem from the Linux permission model or internal Docker networking rules.

• Failure Scenario: Import Error - "Permission Denied" in Sonarr/Radarr Logs

  
  
  
  • Root Cause: This occurs when the Docker container is running under a different User ID than the owner of the media folders on the host machine. If the host folder is owned by root but the container is using PUID 1000, the container cannot move or rename files.
  • Actionable Fix: Execute the command "sudo chown -R 1000:1000 /DATA/Media" in the terminal. This recursively changes the ownership of the media directory to the user matching your PUID/PGID variables.

• Failure Scenario: Search Results Timeout in Prowlarr

  
  
  
  • Root Cause: This is typically caused by DNS resolution failures inside the Docker container or the use of a VPN that does not allow local network bypass for container-to-container communication.
  • Actionable Fix: In the CasaOS app settings for Prowlarr, manually set the DNS to 1.1.1.1 or 8.8.8.8. If using a VPN container, ensure that the Arr stack is not routed through the VPN unless specifically required for tracker access, as this adds unnecessary latency.

• Failure Scenario: "No Indexers Available" despite Prowlarr Link

  
  
  
  • Root Cause: The API synchronization might have failed because the "Base URL" was set incorrectly in the Prowlarr application settings.
  • Actionable Fix: Check the "Full URL" in the Prowlarr app settings within Radarr. Ensure it includes the http:// prefix and the correct port. Test the connection using the "Test" button; if it fails, verify that no firewall on the CasaOS host is blocking internal Docker traffic.

Frequently Asked Questions

Why should I use Prowlarr instead of adding indexers directly to Sonarr?

Prowlarr acts as a centralized proxy that synchronizes all your trackers across multiple applications simultaneously. If a tracker URL changes or you add a new provider, you only have to update it once in Prowlarr rather than manually editing every application in your stack, significantly reducing administrative overhead.

Can I run this Arr stack on a Raspberry Pi?

Yes, the Arr stack is highly efficient on ARM-based systems like the Raspberry Pi 4 or 5. However, you should disable heavy metadata tasks like "Analyze Video Files" in the settings if you notice high CPU usage. Using the Docker-based CasaOS approach ensures that the applications only use the resources they need.

Is a VPN necessary for the entire Arr stack?

Generally, only the download client (qBittorrent) and Prowlarr require a VPN to protect your privacy and bypass ISP-level blocks on trackers. Sonarr and Radarr do not handle torrent traffic directly; they only manage metadata and file organization, so routing them through a VPN often causes unnecessary connectivity issues with metadata providers like TVDB.

What is the advantage of using CasaOS over standard Docker Compose?

CasaOS provides a visual layer that makes managing volumes and environment variables much more intuitive for users who are not comfortable with YAML files. It also offers a built-in file manager and resource monitor, making it easier to troubleshoot storage space or high memory usage at a glance.

How do I update the applications in my Arr stack?

CasaOS will usually notify you when an update is available for an app installed via its App Store. For custom-installed containers, you can go to the settings of the app and click "Update" if the image tag is set to "latest." This pulls the newest version of the container without losing your configuration data.

Upgrade Your Home Lab Media Experience

Building a professional-grade media server is a journey of continuous optimization and refined automation. Explore our advanced guides on setting up Overseerr for request management or Tautulli for Plex monitoring to take your CasaOS ecosystem to the next level of performance.