aria2/IDEA.md

aria2 — THE WHAT

A single Alpine-based Docker image that provides a complete, self-hosted download solution: aria2c handles multi-protocol downloads (HTTP/HTTPS, FTP, SFTP, BitTorrent, Metalink) via a JSON-RPC daemon on port 6800, while AriaNg (a pure-static web UI bundled at build time) is served by nginx on port 80, which also reverse-proxies /jsonrpc and /rpc to aria2c so end users interact with a single port. BitTorrent peer traffic uses port 6888. The design is zero-config on first run: the container seeds /config/aria2/aria2.conf and /config/nginx/nginx.conf from baked-in optimized defaults, a tracker.sh helper refreshes the BitTorrent tracker list at each startup, and users who want RPC authentication simply set RPC_SECRET in the environment.

aria2 — THE HOW

Build flow

Multi-stage Alpine Dockerfile (casjaysdev/alpine base → FROM scratch final).

1. Package install: pkmgr install aria2 bash tini curl wget tzdata ca-certificates unzip jq pwgen nginx installs all components in one layer.
2. Setup scripts (rootfs/root/docker/setup/): 03-files.sh auto-installs everything under rootfs/tmp/ into the image (/etc/aria2/, /etc/nginx/, /usr/local/etc/docker/bin/, etc.). 05-custom.sh performs the wipe-and-replace — removes distro defaults from /etc/aria2/ and /etc/nginx/, installs our optimized configs, and unpacks the pre-bundled AriaNg zip from rootfs/tmp/ariang-src/AriaNg-*.zip into /usr/local/share/ariang/.
3. AriaNg pre-bundle: GitHub SSL is blocked inside the buildx sandbox on this host, so the AriaNg zip must be downloaded on the host first and placed at rootfs/tmp/ariang-src/AriaNg-1.3.13.zip (gitignored) before running buildx.
4. Final stage: FROM scratch + COPY --from=build /. / produces a minimal image with tini as PID 1.

Runtime boot chain

tini → /usr/local/bin/entrypoint.sh → /usr/local/etc/docker/init.d/00-aria2c.sh → /usr/local/etc/docker/bin/start-aria2

• entrypoint.sh seeds /config/ and /data/ on first run (via __initialize_config_dir / __initialize_data_dir), then calls __start_init_scripts which sources and executes init.d/00-aria2c.sh.
• 00-aria2c.sh sources functions/entrypoint.sh, runs hook functions (__run_pre_execute_checks → tracker.sh to refresh BT trackers; __update_conf_files → token substitution: REPLACE_RPC_PORT, REPLACE_SERVER_ADDR, optional rpc-secret toggle, DHT port, log path, file-allocation, AriaNg config overlay), then calls the framework's __run_start_script.
• start-aria2 backgrounds aria2c --conf-path=/config/aria2/aria2.conf, waits for port 6800 to open, then execs nginx -c /config/nginx/nginx.conf -g 'daemon off;' as the foreground process (becomes PID adopted by tini).

Key paths

Path	Role
/usr/bin/aria2c	Download daemon binary
/usr/sbin/nginx	HTTP server binary
/usr/local/share/ariang/	AriaNg static files (index.html, JS, CSS)
/usr/local/etc/docker/bin/start-aria2	Wrapper: backgrounds aria2c, foregrounds nginx
/usr/local/etc/docker/init.d/00-aria2c.sh	Init.d script — wires up the service
/usr/local/bin/tracker.sh	P3TERX BT tracker updater
/config/aria2/aria2.conf	User-editable aria2c config (seeded from rootfs/tmp/etc/aria2/aria2.conf)
/config/nginx/nginx.conf	User-editable nginx config (seeded from rootfs/tmp/etc/nginx/nginx.conf)
/data/downloads/aria2/	Download destination
/data/logs/aria2/aria2.log	aria2c log
/data/logs/nginx/	nginx access + error logs

Config token substitution (00-aria2c.sh __update_conf_files)

Tokens in /config/aria2/aria2.conf replaced at each container start:

Token	Replaced with
REPLACE_RPC_PORT	${RPC_PORT:-6800}
REPLACE_SERVER_ADDR	Container IPv4 (via __get_ip4)
rpc-secret=REPLACE_RPC_SECRET	Commented out unless RPC_SECRET env var is set
dht-listen-port=.*	dht-listen-port=6888
log=.*	log=/data/logs/aria2/aria2.log
file-allocation=.*	file-allocation=prealloc

The AriaNg client config (/config/aria2/aria-ng.config.js) is also overlaid onto the bundled js/aria-ng-*.min.js so the UI auto-connects to the local RPC endpoint without user configuration.

Single init.d design

The framework's __start_init_scripts only reliably runs the first init.d/*.sh. Two separate scripts (00-aria2c.sh + zz-nginx.sh) would only start aria2c. The resolution is a single init.d entry (00-aria2c.sh) pointing at the start-aria2 wrapper script which manages both processes.