schedion/aria2-web-watch repository overview

⁠aria2-web-watch

Container image bundling aria2, the AriaNg single-page UI, nginx, and a watch-directory workflow that feeds new torrents to aria2 via JSON-RPC.

⁠Features

• Serves AriaNg through nginx and proxies JSON-RPC calls back to aria2 on port 6800.
• Fetches the latest AriaNg release during docker build (pin with ARIANG_VERSION=<tag>).
• Mount-ready download directory (/data) and watch directory (/watch) whose ownership matches the requested UID/GID.
• inotify-based watcher automatically queues .torrent files via aria2p add, renaming each to .added after submission.
• Flexible environment variables let you supply custom aria2 configs, session files, directories, and runtime secrets.
• HTTP Basic Auth guards the AriaNg UI (default user aria2 with a generated password persisted under /config), while /jsonrpc stays exposed only via the shared secret for AriaNg and other clients.
• Secrets (RPC token + Basic Auth password) persist under /config so restarts reuse credentials unless you explicitly force regeneration.
• Ships the mkbrr CLI (from autobrr/mkbrr⁠) via Alpine’s edge/testing repository so you can craft torrents directly inside the container.

⁠Building

docker build -t aria2-web-watch .

• Pass --build-arg ARIANG_VERSION=<tag> to pin AriaNg to a specific release instead of latest.
• The image builds on nginx:stable-alpine; no private registry access required.

⁠Running

docker volume create aria2-config
docker run -p 80:80 -p 6800:6800 \
  -e RPC_SECRET="your-secret" \
  -e PUID=1000 -e PGID=1000 \
  -v aria2-config:/config \
  aria2-web-watch

• Visit http://localhost/ for AriaNg; it connects to aria2 through nginx at http://localhost/jsonrpc.
• Publishing port 6800 is optional unless you need direct RPC access from outside the container.
• /data and /watch live inside the container filesystem by default; override via DOWNLOAD_DIR and WATCH_DIR only if you truly need host mounts.
• The entrypoint copies /etc/aria2/aria2.conf.template into ARIA2_CONF before appending runtime values like the RPC secret, download path, and session file.
• The /jsonrpc proxy is enabled by default so AriaNg can reach aria2 via the same origin; set ENABLE_RPC_PROXY=false to disable the nginx proxy if you never want the RPC exposed.
• A lightweight bootstrap script (/ariang-autoconfig.js) seeds AriaNg’s browser storage the first time the UI loads so it automatically targets /jsonrpc. Disable it with ENABLE_ARIANG_AUTOCONFIG=false if you prefer to manage settings manually.
• On first boot the container generates an RPC_SECRET and Basic Auth password (or uses values you provide), stores them under /config, and reuses them on future starts. Set FORCE_RANDOM_RPC_SECRET=true or FORCE_RANDOM_WEBUI_PASSWORD=true if you need one-off rotations.
• Capture the generated credentials from container logs (docker logs <container>) if you rely on the defaults; otherwise, set explicit RPC_SECRET and WEBUI_PASSWORD values for deterministic deployments.
• Customize BitTorrent behavior via BT_LISTEN_PORT (default 6881) and PEER_ID_PREFIX (default A2), and adjust log verbosity with ARIA2_LOG_LEVEL. aria2 logs stream to Docker logs because the process writes directly to stdout.
• Hidden files and directories inside /watch are ignored by default (WATCH_EXCLUDE_REGEX), avoiding Syncthing metadata and similar helper folders.
• /healthz issues a loopback JSON-RPC call (aria2.getVersion) to verify nginx, aria2, and the secret are all working before returning {"status":"ok"}—ideal for Docker/K8s readiness checks.
• Mount /config (or override SECRETS_DIR) if you want those credentials to persist outside the container filesystem.

⁠Docker Compose

Use docker-compose.yml as a starting point, customizing environment variables to taste:

services:
  aria2-web-watch:
    image: schedion/aria2-web-watch:latest
    # build: .  # Uncomment to build locally
    environment:
      RPC_SECRET: "changeme"          # optional; generated & stored if omitted
      WEBUI_USER: "aria2"
      WEBUI_PASSWORD: "changeme"      # optional; generated & stored if omitted
      PUID: "1000"
      PGID: "1000"
      ENABLE_RPC_PROXY: "true"
      ENABLE_ARIANG_AUTOCONFIG: "true"
      BT_LISTEN_PORT: "6881"
      PEER_ID_PREFIX: "A2"
      ARIA2_LOG_LEVEL: "notice"
      WATCH_EXCLUDE_REGEX: "(^|/)\\."
      SKIP_DIR_OWNERSHIP: "false"
      # DOWNLOAD_DIR: "/data"
      # WATCH_DIR: "/watch"
      # SECRETS_DIR: "/config"
      # RPC_SECRET_FILE: "/config/rpc-secret"
      # WEBUI_PASSWORD_FILE: "/config/webui-password"
    ports:
      - "80:80"
      - "6800:6800"
    volumes:
      - aria2-config:/config
      # - ./aria2.conf:/config/aria2.conf.template:ro
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  aria2-config:

docker compose up -d

⁠Environment variables

Mount or override the directories referenced above to keep state outside the container. The entrypoint creates missing directories and session files before starting services.

⁠AriaNg auto-config & reset

• When ENABLE_ARIANG_AUTOCONFIG=true, the entrypoint injects an inline config block (exposing runtime data like the generated RPC secret) followed by /ariang-autoconfig.js. The script runs before AriaNg initializes and creates or updates localStorage['AriaNg.Options'], ensuring the host/port/protocol and base64-encoded secret point to /jsonrpc on the same origin.
• If you prefer to manage settings yourself (or ship a custom AriaNg build), set ENABLE_ARIANG_AUTOCONFIG=false; the script is removed and the UI will prompt you for RPC details.
• AriaNg stores its preferences in your browser. To return to the auto-connect defaults later, open AriaNg → Settings → AriaNg → Reset AriaNg Settings (or clear the AriaNg.* entries from localStorage) and reload the page so /ariang-autoconfig.js can repopulate them.

⁠Watch directory workflow

1. Drop a .torrent file into the watch directory (default /watch).
2. inotifywait emits an event and the watcher submits the torrent via aria2p add.
3. Successful submissions are renamed to <original>.added so you have a quick audit trail; failures are logged but left untouched.

⁠Inspiration

Watch directory handling and inotify-based queuing are inspired by mushanyoung/aria2-watching⁠. Consult the aria2⁠ project for advanced JSON-RPC options and authentication settings.

⁠Development notes

• Text files are normalized to LF via .gitattributes; ensure your Git tooling honors those settings to avoid cross-platform conflicts.
• There are no automated tests—run docker build and docker run locally when changing the Dockerfile, entrypoint, or configs.

⁠mkbrr CLI

The container installs mkbrr⁠ from Alpine’s testing repository under /usr/local/bin/mkbrr. Run it via docker exec whenever you need to create or inspect torrents, for example:

docker exec -it aria2-web-watch mkbrr create --path /data/myfile.iso

Whenever Alpine updates mkbrr you’ll pick up the new version on the next image rebuild; no extra build arguments required.