chore: initial sanitized public snapshot

2026-07-18 16:01:12 +08:00
commit 7c6b6a3746
321 changed files with 76896 additions and 0 deletions
@@ -0,0 +1,223 @@
+# 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](../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
+
+```powershell
+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:
+
+```powershell
+$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](examples/aria2.conf).
+
+### 3. Validate the config
+
+```powershell
+.\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:
+
+```powershell
+.\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](examples/aria2-rust-pro.service).
+
+### 5. Verify the deployment
+
+Version:
+
+```powershell
+.\target\release\aria2-rust-pro.exe --version
+```
+
+RPC probe:
+
+```powershell
+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:
+
+```powershell
+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](../../docker/.env.example) to `docker/.env`
+and replace the example values:
+
+```powershell
+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
+
+```powershell
+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
+
+```powershell
+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:
+
+```powershell
+docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f
+```
+
+Version inside the container:
+
+```powershell
+docker exec aria2-rust-pro aria2c --version
+```
+
+RPC probe from the host:
+
+```powershell
+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:
+
+```powershell
+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
+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.