aria2 Docker & NAS Setup Guide — Aria2 Pro & AriaNg

1. The 3-Tier Container Architecture

A production aria2 Docker environment consists of three interconnected modules running in lightweight Alpine containers:

⚙️

1. Core Engine (aria2-pro)

Enhanced aria2 daemon with high IOPS disk caching, multi-protocol engine (HTTP, FTP, BitTorrent, Metalink), and WebSocket JSON-RPC listening on port 6800.

📡

2. Auto Tracker Sync

Background cron daemon fetching curated live BT trackers from GitHub every 24 hours to eliminate stalled/dead torrents and discover maximum peer swarms.

🖥️

3. AriaNg WebUI

Zero-overhead HTML5 responsive web dashboard served on port 6880 for managing downloads from mobile phones, tablets, and desktop browsers.

2. Production-Grade docker-compose.yml

Save the following configuration as docker-compose.yml in your dedicated deployment directory (e.g. /opt/aria2/ or /volume1/docker/aria2/):

# docker-compose.yml

version: '3.8'

services:
  aria2-pro:
    container_name: aria2-pro
    image: p3terx/aria2-pro:latest
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"
    environment:
      - PUID=1000
      - PGID=1000
      - RPC_SECRET=YourSuperSecureToken99! # Replace with a strong secret
      - RPC_PORT=6800
      - LISTEN_PORT=6888
      - TRACKERS_AUTO_UPDATE=true         # Auto-fetch fresh BT Trackers daily
      - DISK_CACHE=64M                    # Memory cache buffer to protect SSDs/HDDs
      - IPV6_MODE=false                   # Set true if your ISP has native IPv6
      - TZ=UTC                            # Replace with your timezone (e.g. America/New_York)
    volumes:
      - ./aria2-config:/config            # Persistent session & custom script storage
      - ./downloads:/downloads            # Destination folder for completed downloads
    ports:
      - "6800:6800"                       # RPC WebSocket / HTTP API
      - "6888:6888"                       # BitTorrent TCP peer discovery
      - "6888:6888/udp"                   # BitTorrent DHT UDP peer discovery

  ariang:
    container_name: ariang
    image: p3terx/ariang:latest
    restart: unless-stopped
    ports:
      - "6880:6880"                       # WebUI Dashboard
    depends_on:
      - aria2-pro

Key Environment Variables Explained:

PUID / PGID: Sets the user and group permissions of downloaded files so other container apps (Plex, Jellyfin, Sonarr, Radarr, Samba) can read and modify them without permission errors.
DISK_CACHE=64M: Allocates RAM buffer chunks. Prevents continuous micro-writes to mechanical NAS disks, dramatically extending drive life.
LISTEN_PORT=6888: Dedicated BitTorrent incoming port. Forward 6888 TCP and UDP on your home router for active Connectable status.

3. Platform-Specific Deployment Walkthrough

A. Linux Server (Ubuntu / Debian / AlmaLinux / Raspberry Pi)

Create directories, assign user ownership, and launch the stack in daemon mode:

mkdir -p /opt/aria2/{aria2-config,downloads}
cd /opt/aria2
# Copy docker-compose.yml into /opt/aria2/
sudo chown -R 1000:1000 /opt/aria2
docker compose up -d

B. Synology NAS (DSM 7.2+ Container Manager)

Open File Station and create folders: /docker/aria2/config and /volume1/downloads.
Open Container Manager → Project → Create.
Set Project Name: aria2, Path: /docker/aria2, Source: Create docker-compose.yml.
Paste the compose configuration, update volume paths to /volume1/downloads:/downloads, and click Done.

C. QNAP Container Station / Unraid

On QNAP Container Station, navigate to Applications → Create and paste the Compose file. On Unraid, use the Compose plugin or map appdata to /mnt/user/appdata/aria2 and downloads to /mnt/user/downloads/.

4. Secure Remote Access & HTTPS Reverse Proxy

When accessing AriaNg over public HTTPS (e.g. https://aria2.yourdomain.com), modern web browsers block unencrypted HTTP/WS requests to port 6800 due to Mixed Content Security Policies. You must configure an SSL WebSocket (WSS) reverse proxy:

# Nginx Reverse Proxy with WSS WebSocket Support

server {
    listen 443 ssl http2;
    server_name aria2.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    # 1. Route WebUI Frontend
    location / {
        proxy_pass http://127.0.0.1:6880;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 2. Route JSON-RPC Secure WebSocket (WSS)
    location /jsonrpc {
        proxy_pass http://127.0.0.1:6800/jsonrpc;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}

5. Post-Download Automation Hooks (Rclone / Auto-Extract)

aria2 supports lifecycle hooks via the on-download-complete trigger. You can automatically upload finished downloads to Google Drive or OneDrive via Rclone, or unpack zip/rar archives:

How Event Hooks Work:

In ./aria2-config/clean.sh, aria2 passes 3 positional parameters: $1 (GID), $2 (File count), and $3 (File path). You can trigger custom notifications (Telegram, Discord, ServerChan) or Rclone sync scripts automatically.

6. Troubleshooting & Diagnostics

Q1: How do I view live server logs?

Run docker compose logs -f aria2-pro to inspect active connections, tracker sync output, and disk write status.

Q2: BitTorrent download speed is 0 KB/s or DHT shows 0 nodes

Fix: Ensure port 6888 UDP is mapped in your compose file and forwarded on your router. Bootstrap DHT nodes by starting a popular Ubuntu torrent or manually updating trackers from our Trackers Hub.

Q3: "AriaNg disconnected" or RPC connection failed

Fix: Open AriaNg settings → RPC configuration. Verify the RPC Host matches your server IP, Port is 6800 (or 443 if using reverse proxy), and RPC Secret matches your RPC_SECRET token.