aria2-rust-pro/docs/deployment/README.md

Deployment Guide

This is the concrete deployment guide for the current aria2-rust-pro repository state. It covers the two deployable paths that exist today:

• native host deployment from a local Cargo build
• local Docker deployment from docker/Dockerfile

For migration-specific advice, start with ../migration/README.md.

Current Deployment Facts

• Native host installs are source-build-first today.
• The self-hosted Gitea v1.0.0 release carries the first Windows archive, Docker image tar, manifests, and checksum assets.
• Docker deployment is still local-build-first or tar-import-first; there is no documented published container registry tag yet.
• Native RPC startup requires --enable-rpc on the command line. Putting enable-rpc=true only in the config file is not enough to switch the CLI into the long-running RPC server path.
• --daemon currently selects the RPC-daemon command surface; it should not be treated as a service-manager replacement or as proof of POSIX background forking.

Native Host Deployment

1. Build the binary

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

The resulting binary is:

• Windows: target\release\aria2-rust-pro.exe
• Linux: target/release/aria2-rust-pro

2. Prepare the runtime directories

On Windows, a simple starting layout is:

$Root = "C:/ProgramData/aria2-rust-pro"
New-Item -ItemType Directory -Force "$Root", "$Root/downloads", "$Root/state" | Out-Null
Copy-Item .\docs\deployment\examples\aria2.conf "$Root/aria2.conf"

On Linux, the same layout works under /var/lib/aria2-rust-pro or /srv/aria2-rust-pro.

Edit the copied config so that dir=, input-file=, and save-session= point at your real directories, and replace rpc-secret= with a strong private value before enabling RPC. A ready-to-edit template lives at examples/aria2.conf.

3. Validate the config

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

This should exit cleanly with no config-parse error.

4. Start the RPC process

For a direct foreground launch:

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

For Linux service managers, keep the process in the foreground and let the supervisor own restart behavior. A sample unit file lives at examples/aria2-rust-pro.service.

5. Verify the deployment

Version:

.\target\release\aria2-rust-pro.exe --version

RPC probe:

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

Session file presence:

Test-Path C:/ProgramData/aria2-rust-pro/state/aria2.session

Docker Deployment

docker/Dockerfile, docker/entrypoint.sh, and the Cargo-native Docker smoke commands define the current Docker deployment shape. Use the daemon-free and daemon-backed smokes below to verify the current workspace snapshot before calling a local deployment ready.

When the daemon is available, a portable local image tar can also be staged with xtask docker export-local; scripts/docker/export-local.ps1 remains a compatibility wrapper.

1. Prepare the env file

Copy ../../docker/.env.example to docker/.env and replace the example values:

Copy-Item .\docker\.env.example .\docker\.env

Set a strong RPC_SECRET before starting compose. The compose file refuses an empty secret and binds the host RPC port to 127.0.0.1 by default; widen RPC_BIND_ADDRESS only when the host network is trusted.

2. Review the persistent volume paths

docker/docker-compose.yml currently mounts:

• ../.local/docker/config to /config
• ../.local/docker/downloads to /downloads

If your persistent data lives elsewhere, change those bind mounts before the first start.

3. Build and start the container

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

This builds aria2-rust-pro:local, starts the aria2-rust-pro container, and exposes the configured RPC and listen ports.

4. Inspect the generated runtime config

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

The entrypoint:

• copies /defaults/aria2.conf to /config/aria2.conf only when the base file does not already exist
• ensures /config/aria2.session exists
• appends env-derived overrides into /run/aria2-rust-pro/aria2.generated.conf

5. Verify RPC and logs

Logs:

docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f

Version inside the container:

docker exec aria2-rust-pro aria2c --version

RPC probe from the host:

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

Current Docker behavior

The current entrypoint does more than simple port/env mapping:

• it seeds bt-tracker= from docker/defaults/bt-tracker.txt
• SPECIAL_MODE=move or SPECIAL_MODE=rclone appends on-download-complete=...
• UPDATE_TRACKERS=true runs the bundled tracker updater script

Those entrypoint behaviors are covered by both xtask docker smoke-local and the daemon-backed xtask docker smoke. The live container path now boots, serves RPC, and keeps those Docker-specific config rewrites active in /run/aria2-rust-pro/aria2.generated.conf.

Smoke Commands

Use the canonical Cargo-native smoke commands after any packaging or deployment change:

rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker smoke-local
rtk cargo run --manifest-path .\xtask\Cargo.toml -- docker smoke --tag aria2-rust-pro:smoke

xtask docker smoke-local proves the entrypoint/config-generation path without a Docker daemon. xtask docker smoke builds the image and probes live JSON-RPC inside a running container.

The PowerShell scripts remain compatibility wrappers with the same local options:

powershell -ExecutionPolicy Bypass -File .\scripts\docker\smoke-local.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\docker\smoke.ps1 -Tag aria2-rust-pro:smoke

The daemon-backed wrapper forwards -Build, -HostRpcPort, -RpcSecret, and -SpecialMode to the matching xtask docker smoke options.

Known Deployment Limits Today

• No documented published image tag yet; Docker deployment is still local-build-first or tar-import-first from the release asset.
• The self-hosted Gitea v1.0.0 release includes the first Windows archive and Docker tar assets; a broader multi-platform archive matrix is still future work.
• The Docker entrypoint now applies tracker snapshot, tracker-update, and special-mode hook rewrites, but this is still a local-build-first deployment lane rather than a published image-release matrix.
• The repo ships a sample systemd unit, but not a first-party Windows service wrapper or installer.