chore: initial sanitized public snapshot
This commit is contained in:
Aria2 Rust Pro Contributors
@@ -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.
|
||||
@@ -0,0 +1,18 @@
|
||||
[Unit]
|
||||
Description=aria2-rust-pro RPC service
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=aria2
|
||||
Group=aria2
|
||||
WorkingDirectory=/var/lib/aria2-rust-pro
|
||||
ExecStart=/opt/aria2-rust-pro/bin/aria2-rust-pro --conf-path /etc/aria2-rust-pro/aria2.conf --enable-rpc
|
||||
Restart=on-failure
|
||||
RestartSec=2
|
||||
NoNewPrivileges=true
|
||||
LimitNOFILE=65535
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,20 @@
|
||||
# Minimal native deployment template for aria2-rust-pro.
|
||||
# Edit the paths and rpc-secret before first use.
|
||||
|
||||
dir=/srv/aria2-rust-pro/downloads
|
||||
input-file=/srv/aria2-rust-pro/state/aria2.session
|
||||
save-session=/srv/aria2-rust-pro/state/aria2.session
|
||||
save-session-interval=60
|
||||
continue=true
|
||||
split=5
|
||||
max-connection-per-server=16
|
||||
min-split-size=1K
|
||||
piece-length=1K
|
||||
enable-rpc=true
|
||||
rpc-listen-port=6800
|
||||
rpc-secret=replace-with-a-strong-rpc-secret
|
||||
listen-port=6888
|
||||
dht-listen-port=6888
|
||||
disable-ipv6=true
|
||||
disk-cache=64M
|
||||
check-certificate=true
|
||||
Reference in New Issue
Block a user