# 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.