Learn Aria2 - Production-Ready Setup

#Introduction

In episode 19 you learned to read failures. Now it's time to design a system that rarely fails and is easy to recover when it does: running aria2 as a daemon, making it a systemd service that auto-starts, rotating logs so the disk never fills up, then deploying to Docker and NAS. This is the bridge from "aria2 on a laptop" to "aria2 as infrastructure".

#Daemon Mode: -D

Until now aria2c ran in the foreground — it clung to the terminal, and a closed terminal killed it. For production, run it as a daemon: a process detached from the terminal, running in the background.

aria2c -D --conf-path=/etc/aria2/aria2.conf

-D makes aria2c fork itself and immediately return the prompt. All settings — download directory, RPC, speed limits — are taken from the configuration file, so the command stays short and consistent. Check that it's alive with pgrep -af aria2c or via the logs.

Note one important detail: a daemon is only useful if its life is managed by something bigger. If the server reboots, who starts it again? The answer is systemd.

#systemd Service: Auto-Start and Auto-Restart

systemd is the standard service manager on modern distros. It makes aria2 start at boot, restart on crash, and keeps its logs. Create the unit file:

aria2.service

[Unit]
Description=aria2 download daemon
After=network.target
 
[Service]
Type=forking
User=aria2
Group=aria2
ExecStart=/usr/bin/aria2c -D --conf-path=/etc/aria2/aria2.conf
Restart=on-failure
RestartSec=10
 
[Install]
WantedBy=multi-user.target

Type=forking because -D makes the daemon fork; User=aria2 ensures the daemon doesn't run as root; Restart=on-failure brings a crashed service back after a 10-second delay. Enable and start it:

sudo useradd -r -m -d /var/lib/aria2 aria2
sudo systemctl daemon-reload
sudo systemctl enable --now aria2

Check its health and read the service logs:

systemctl status aria2
journalctl -u aria2 -f

#Log Rotation: logrotate

A daemon running for months produces a log that keeps growing. Logrotate truncates and compresses it automatically:

/var/log/aria2/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

copytruncate matters for aria2 because it opens the log file itself and doesn't listen to rotation signals. With this configuration, 14 days of history stay compressed without ever filling the disk.

#Docker: aria2 in a Container

In container environments, aria2 runs inside an image that already bundles the daemon and web UI together. One popular option is wappjzdstar/aria2 — a small image that combines the aria2 daemon and AriaNg:

docker run -d --name aria2 \
  -p 6800:6800 \
  -p 6881-6999:6881-6999 \
  -p 8080:80 \
  -v /srv/downloads:/data \
  -v /srv/aria2/conf:/conf \
  -e SECRET=RAHASIA \
  --restart unless-stopped \
  wappjzdstar/aria2:latest

Let's break down the choices above:

• -p 6800:6800 — the RPC port, used by applications and AriaNg to talk to the daemon.
• -p 6881-6999:6881-6999 — BitTorrent and DHT traffic, from episode 19.
• -p 8080:80 — the AriaNg web UI, available on port 80 inside the container.
• -v — persistent volumes: download data and configuration live on the host, not inside a container that can be discarded at any time.
• --restart unless-stopped — the container comes back after a reboot or crash.

Volumes are the most important decision: the container can be replaced, but /srv/downloads and /srv/aria2/conf are yours forever. If you prefer to declare everything, here's the Compose version:

services:
  aria2:
    image: wappjzdstar/aria2:latest
    restart: unless-stopped
    ports:
      - "6800:6800"
      - "6881-6999:6881-6999"
      - "8080:80"
    volumes:
      - /srv/downloads:/data
      - /srv/aria2/conf:/conf
    environment:
      SECRET: RAHASIA

#NAS and Router: Synology and OpenWrt

aria2's greatest value often shows up not on cloud servers, but on the devices that stay on at home.

#Synology NAS

On DSM, you can install a community aria2 package (for example from SynoCommunity) that automatically creates a service and a download shared folder. A more controlled alternative: run the Docker image above through the Container Manager package, then point the volume at a shared folder — for example /volume1/downloads. The result: the NAS becomes an always-on download center, with files stored directly where you normally manage them.

#OpenWrt Router

OpenWrt has an aria2 package in opkg:

opkg update
opkg install aria2 luci-app-aria2

The luci-app-aria2 package provides a LuCI (web) interface for configuring and monitoring the daemon. One important note from episode 19: make sure the router firewall allows BitTorrent ports, and check whether the router's NAT lets peers reach those ports.

#Production Daemon Checklist

Before closing the episode, here's a checklist summarizing the key decisions:

• Dedicated user — the daemon runs as aria2, not root.
• Centralized configuration — all options in /etc/aria2/aria2.conf, not a mix of arguments.
• Auto-start — systemd enable --now or Docker restart unless-stopped.
• Auto-restart — Restart=on-failure or a container restart policy.
• Rotating logs — logrotate with copytruncate.
• Persistent volumes — data and configuration outside the container or daemon.
• Secure RPC — a strong secret and binding to the right interface (from episode 14).

#Closing

Episode 20 raised aria2 to production level: a daemon with -D, a systemd unit for auto-start and auto-restart, log rotation with logrotate, Docker deployment with persistent volumes and the wappjzdstar/aria2 image, plus Synology NAS and OpenWrt router integration.

The key takeaway: production isn't about features, it's about resilience. A daemon without a supervisor, logs without rotation, or data without volumes are just problems that haven't surfaced yet.

In the next episode, episode 21, we connect aria2 with the world around it: integration with tools and workflows — AriaNg, browser extensions, checksum verification, and modern download workflows on servers. See you then!