Migration Guide

This guide reflects the current active modernization state from GOAL-modern.md and progress.md for aria2-rust-pro. It is written for two existing audiences:

users running the current Aria2-Pro-Core host binary directly
users running the current Aria2-Pro-Docker container shape

The short version is:

aria2-style config syntax, session files, and RPC clients are intended to carry forward
the native host binary is now aria2-rust-pro, not a published aria2-pro-core drop-in tarball
the Docker image keeps the legacy env variable names and now maps the current Pro Docker knobs through the entrypoint/runtime config path

Before You Cut Over

Make a copy of the three things that matter before any migration:

your current aria2.conf
your aria2.session plus any adjacent .aria2 control files
the exact runtime command or compose file you use today

For Docker users, also record the current bind mounts or named volumes so that you know where /config and /downloads live on disk.

Compatibility Snapshot

Surface	Current `aria2-rust-pro` status	Migration meaning
aria2-style config file	compatible target; current parser/runtime covers the common Pro/Core and Docker paths used here	keep your existing config and validate it with `--dry-run` before switching traffic
Session and input files	current session persistence is implemented and covered by tests	keep existing session paths; do not delete `aria2.session` during cutover
JSON-RPC and XML-RPC	current RPC surface is implemented enough for representative aria2 clients	reuse the same client URLs and tokens after you verify the new port and secret
Native packaging	the self-hosted Gitea `v1.0.0` release includes a Windows archive plus checksums, while broader platform archives remain future work	use the release archive where it matches your host, otherwise plan for a local Cargo build or your own packaged artifact
Docker env names	the current Pro Docker env set is accepted and mapped by the entrypoint	keep the same env names, then verify the generated runtime config before cutover

From `Aria2-Pro-Core`

What stays the same

Keep your existing aria2.conf format.
Keep your current aria2.session.
Keep the Pro/Core option deltas that already exist in this rewrite, including the relaxed split and retry knobs tracked in the compatibility ledger.

What changes

Area	Old Core habit	`aria2-rust-pro` now
Binary name	usually `aria2c`	native host binary is `aria2-rust-pro`
Install flow	download a release tarball and move `aria2c` into place	build with Cargo or deploy your own packaged artifact
RPC startup	config plus your old service wrapper	native startup still needs `--enable-rpc` on the command line to enter the long-running RPC server path
Backgrounding	old wrappers often daemonized the process	do not rely on `--daemon` as a POSIX fork; supervise the foreground process with systemd, NSSM, Task Scheduler, or another service manager

Recommended host cutover

Build the new binary without overwriting the old one yet:

cargo build --release -p aria2-rust-pro-cli --bin aria2-rust-pro

Stage a new config root and copy your current config/session into it.

Validate the config before swapping any service definition:

.\target\release\aria2-rust-pro.exe --dry-run --conf-path C:/ProgramData/aria2-rust-pro/aria2.conf

Update your service or launcher to point at the new binary and keep --enable-rpc on the command line:

.\target\release\aria2-rust-pro.exe --conf-path C:/ProgramData/aria2-rust-pro/aria2.conf --enable-rpc

Probe RPC before you disable the old service:

xh post http://127.0.0.1:6800/jsonrpc jsonrpc=2.0 id=migrate method=aria2.getVersion params:='["token:replace-with-a-strong-rpc-secret"]'


If your surrounding scripts still hardcode `aria2c`, keep the old binary in
place until you have either updated those scripts or installed your own wrapper
or symlink that points `aria2c` to `aria2-rust-pro`.

## From `Aria2-Pro-Docker`

### What carries forward

- `/config/aria2.conf` remains the base config path.
- `/config/aria2.session` remains the session file path.
- `/downloads` remains the default download root.
- the container still accepts the familiar Pro Docker env variable names

### What is different from the old Docker behavior

| Env or behavior | Old Pro Docker expectation | `aria2-rust-pro` now |
| --- | --- | --- |
| `RPC_SECRET` | old images often rewrote `aria2.conf` in place and could expose compatibility fallbacks | when set, it appends `rpc-secret` and `rpc-listen-all=true` into the generated runtime config; when empty, the entrypoint warns and keeps RPC loopback-only unless your base config overrides it |
| `RPC_PORT` | runtime env + config rewrite | mapped into `/run/aria2-rust-pro/aria2.generated.conf` |
| `LISTEN_PORT` | runtime env + config rewrite | mapped into generated config for both `listen-port` and `dht-listen-port` |
| `DISK_CACHE` | runtime env + config rewrite | mapped into generated config |
| `IPV6_MODE` | runtime env + config rewrite | mapped into generated config as `disable-ipv6=true/false` |
| `UPDATE_TRACKERS` | functional startup/runtime knob | supported by the entrypoint; when enabled it runs the bundled tracker updater against the generated config |
| `CUSTOM_TRACKER_URL` | functional tracker-updater input | supported by the entrypoint as the tracker updater source URL |
| `SPECIAL_MODE` | functional mode hook | supported by the entrypoint for `move` and `rclone`; it copies default scripts and appends `on-download-complete=` to the generated config |
| Config mutation | old image families often rewrote `/config/aria2.conf` directly | this image copies `/config/aria2.conf` only when missing, then writes overrides to `/run/aria2-rust-pro/aria2.generated.conf` |

### Recommended Docker staging flow

1. Stop the old container without deleting the existing `/config` and
`/downloads` data.

2. Copy `docker/.env.example` to `docker/.env` and set your real values.

3. If your current data lives somewhere other than the compose defaults, adjust
the volume paths in `docker/docker-compose.yml` before first start.

4. Build and start the replacement container:

```powershell
docker compose --env-file docker/.env -f docker/docker-compose.yml up -d --build

Confirm that the container preserved the base config and generated the runtime overlay:

docker exec aria2-rust-pro sh -lc "test -f /config/aria2.conf && sed 's/^rpc-secret=.*/rpc-secret=<redacted>/' /run/aria2-rust-pro/aria2.generated.conf"

Probe RPC from the host: