From 475cb465579c62343f43333e14bbcc7647d20389 Mon Sep 17 00:00:00 2001
From: saltbo <saltbo@foxmail.com>
Date: Sat, 6 Jun 2026 20:34:16 -0400
Subject: [PATCH] fix(docker): use host hostname for downloader

---
 deploy/docker-compose.rustfs.yml |  1 +
 deploy/docker-compose.yml        |  1 +
 docker-compose.yml               |  1 +
 docs/deploy/docker.md            | 16 ++++++++++++++++
 4 files changed, 19 insertions(+)

diff --git a/deploy/docker-compose.rustfs.yml b/deploy/docker-compose.rustfs.yml
index e0e01099..44c8bcdf 100644
--- a/deploy/docker-compose.rustfs.yml
+++ b/deploy/docker-compose.rustfs.yml
@@ -31,6 +31,7 @@ services:
   downloader:
     image: ghcr.io/saltbo/zpan:latest-cli
     command: ["downloader", "up"]
+    hostname: "${HOSTNAME:-zpan-downloader}"
     ports:
       - "${ZPAN_BT_PORT:-6881}:6881/tcp"
       - "${ZPAN_BT_PORT:-6881}:6881/udp"
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index 9915bd0c..668bf50b 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -23,6 +23,7 @@ services:
 
   downloader:
     image: ghcr.io/saltbo/zpan:latest-cli
+    hostname: "${HOSTNAME:-zpan-downloader}"
     ports:
       - "${ZPAN_BT_PORT:-6881}:6881/tcp"
       - "${ZPAN_BT_PORT:-6881}:6881/udp"
diff --git a/docker-compose.yml b/docker-compose.yml
index b9ac1d34..7e8f9c01 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -25,6 +25,7 @@ services:
     build:
       context: .
       target: cli
+    hostname: "${HOSTNAME:-zpan-downloader}"
     ports:
       - "${ZPAN_BT_PORT:-6881}:6881/tcp"
       - "${ZPAN_BT_PORT:-6881}:6881/udp"
diff --git a/docs/deploy/docker.md b/docs/deploy/docker.md
index d5e692c9..731a4450 100644
--- a/docs/deploy/docker.md
+++ b/docs/deploy/docker.md
@@ -39,6 +39,22 @@ ports:
 
 Keep that port reachable from the internet if you want effective seeding and better peer connectivity. If multiple downloader containers run on the same host, give each one a different host port, for example `ZPAN_BT_PORT=6882`, while keeping the container side mapped to `6881`.
 
+### Remote downloader hostname
+
+Docker gives containers a generated hostname unless one is configured. The downloader uses the OS hostname during registration and heartbeats, so the compose files set the container hostname from the host environment:
+
+```yaml
+hostname: "${HOSTNAME:-zpan-downloader}"
+```
+
+On hosts where `HOSTNAME` is not exported, pass it when starting compose:
+
+```sh
+HOSTNAME="$(hostname)" docker compose -f deploy/docker-compose.yml up -d
+```
+
+If the downloader has already registered with a generated container hostname, change the hostname before registering a fresh downloader. The heartbeat hostname updates after restart, but the display name shown in the admin table is the name captured at registration time.
+
 ## Turso (libSQL) opt-in
 
 Set `TURSO_DATABASE_URL` to switch from local SQLite to a Turso (or self-hosted libSQL) database. `TURSO_AUTH_TOKEN` is required for remote URLs; it can be omitted for local `file://` URLs.