fix(docker): clarify ADMIN_PASSWORD mapping and ARM AIO :dev (#385)

Map ADMIN_PASSWORD into compose containers, log bootstrap set=yes/no,
and document amd64-only AIO :dev plus split/dev-arm workarounds for arm64.

Refs #385

Thanks: INSOLVE (Honorary); Marco Jakobs (@jacotec); MyNameisStitch (@MyNameisStitch); Redspin (@playerumpknow)

.github/workflows/docker-publish.yml

@@ -34,7 +34,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Image tag (empty or latest = push latest + VERSION; else custom tag)'
+        description: 'Image tag (empty or latest = push latest + VERSION; else custom tag). Use tag=dev for amd64-only AIO :dev; use a tip tag such as dev-arm for multi-arch AIO (issue #385 ARM retest).'
         required: false
         default: 'latest'
         type: string
@@ -270,7 +270,8 @@ jobs:
         id: plats
         run: |
           # :dev republish (branch push or dispatch tag=dev): amd64 only.
-          # Full multi-arch on main, tags, release, and other dispatch tags.
+          # Full multi-arch on main, tags, release, and other dispatch tags
+          # (e.g. workflow_dispatch tag=dev-arm for ARM retest — issue #385).
           if { [ "${{ github.event_name }}" = "push" ] && [ "${{ github.ref }}" = "refs/heads/dev" ]; } \
              || { [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ github.event.inputs.tag }}" = "dev" ]; }; then
             echo "platforms=linux/amd64" >> "$GITHUB_OUTPUT"

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## [Unreleased]
 
+### Fixed
+- **Docker admin bootstrap clarity (#385 follow-up):** Compose files map `ADMIN_PASSWORD=${ADMIN_PASSWORD:-}` into the container (not only `INIT_ADMIN_*` / `DEFAULT_ADMIN_*`). Bootstrap logs `set=yes|no` without printing the password. Docs note AIO `:dev` is amd64-only — ARM hosts should use split compose, local AIO build, or multi-arch tip tag `dev-arm`.
+
 ### Changed
 - _(none yet)_
 

docker-compose.quick.macvlan.yml

@@ -45,6 +45,8 @@ services:
       - ENCRYPTED_ONLY=1
       - AUTH_DB_PATH=/app/data/auth.db
       # Admin credentials (first run only; existing users are not overwritten).
+      # Do NOT comment these out — host ADMIN_PASSWORD only reaches the container when mapped (issue #385).
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - INIT_ADMIN_USER=${ADMIN_USERNAME:-admin}
       - INIT_ADMIN_PASS=${ADMIN_PASSWORD:-}
       # Set RELAY_SERVERS=MACVLAN_IPV4:21117 when clients are off-LAN (see DOCKER_QUICKSTART.md).
@@ -102,6 +104,8 @@ services:
       # - PUBLIC_RELAY_SERVER=gateway.example.net
       # - PUBLIC_API_URL=https://api.example.net:21121
       # Admin credentials (first run only; existing users are not overwritten).
+      # Do NOT comment these out — host ADMIN_PASSWORD only reaches the container when mapped (issue #385).
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - DEFAULT_ADMIN_USERNAME=${ADMIN_USERNAME:-admin}
       - DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - PUB_KEY_PATH=/opt/rustdesk/id_ed25519.pub

docker-compose.quick.single.macvlan.yml

@@ -61,6 +61,8 @@ services:
       - BETTERDESK_DOCKER_LAYOUT=single
       - BETTERDESK_IMAGE_TAG=${BETTERDESK_IMAGE_TAG:-3.5.80}
       - AUTH_DB_PATH=/app/data/auth.db
+      # Do NOT comment these out — host ADMIN_PASSWORD only reaches the container when mapped (issue #385).
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - INIT_ADMIN_USER=${ADMIN_USERNAME:-admin}
       - INIT_ADMIN_PASS=${ADMIN_PASSWORD:-}
       - DEFAULT_ADMIN_USERNAME=${ADMIN_USERNAME:-admin}

docker-compose.quick.single.yml

@@ -101,6 +101,7 @@ services:
       # Do NOT comment these out — ADMIN_PASSWORD on the host shell only reaches
       # the container when referenced here (issue #385). Fresh installs also need
       # DEFAULT_ADMIN_PASSWORD for the Node.js panel bootstrap.
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - INIT_ADMIN_USER=${ADMIN_USERNAME:-admin}
       - INIT_ADMIN_PASS=${ADMIN_PASSWORD:-}
       - DEFAULT_ADMIN_USERNAME=${ADMIN_USERNAME:-admin}

docker-compose.quick.yml

@@ -60,6 +60,8 @@ services:
       # RustDesk client folders/groups (issue #138). Ignored when DB_URL is postgres://.
       - AUTH_DB_PATH=/app/data/auth.db
       # Admin credentials (first run only; existing users are not overwritten).
+      # Do NOT comment these out — host ADMIN_PASSWORD only reaches the container when mapped (issue #385).
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - INIT_ADMIN_USER=${ADMIN_USERNAME:-admin}
       - INIT_ADMIN_PASS=${ADMIN_PASSWORD:-}
       - SQLITE_AUTH_DB_MODE=${SQLITE_AUTH_DB_MODE:-}
@@ -124,6 +126,8 @@ services:
       # - PUBLIC_RELAY_SERVER=gateway.example.net
       # - PUBLIC_API_URL=https://api.example.net:21121
       # Admin credentials (first run only; existing users are not overwritten).
+      # Do NOT comment these out — host ADMIN_PASSWORD only reaches the container when mapped (issue #385).
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - DEFAULT_ADMIN_USERNAME=${ADMIN_USERNAME:-admin}
       - DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - SQLITE_AUTH_DB_MODE=${SQLITE_AUTH_DB_MODE:-}

docker-compose.single.yml

@@ -88,6 +88,7 @@ services:
       # Do NOT comment these out — ADMIN_PASSWORD on the host shell only reaches
       # the container when referenced here (issue #385).
       #   ADMIN_PASSWORD=YourSecurePassword123 docker compose -f docker-compose.single.yml up -d --build
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
       - INIT_ADMIN_USER=${ADMIN_USERNAME:-admin}
       - INIT_ADMIN_PASS=${ADMIN_PASSWORD:-}
       - DEFAULT_ADMIN_USERNAME=${ADMIN_USERNAME:-admin}

docker/bootstrap-admin-credentials.sh

@@ -137,6 +137,7 @@ if [ -n "${INIT_ADMIN_PASS:-}" ] || [ -n "${DEFAULT_ADMIN_PASSWORD:-}" ]; then
     sync_exports
     _env_pass="${INIT_ADMIN_PASS:-$DEFAULT_ADMIN_PASSWORD}"
     if [ -n "$_env_pass" ]; then
+        echo "Bootstrap: INIT_ADMIN_PASS/DEFAULT_ADMIN_PASSWORD set=yes (password not logged)"
         run_as_betterdesk mkdir -p "$CREDS_DIR" 2>/dev/null || true
         if [ ! -f "$CREDS_FILE" ] && ! primary_database_has_users; then
             _creds_content="Admin Username: ${ADMIN_USER}
@@ -153,6 +154,8 @@ Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
     return 0 2>/dev/null || exit 0
 fi
 
+echo "Bootstrap: INIT_ADMIN_PASS/DEFAULT_ADMIN_PASSWORD set=no (will use credentials file or generate)"
+
 run_as_betterdesk mkdir -p "$CREDS_DIR" 2>/dev/null || true
 
 # Reuse an existing shared credential before trying to acquire the creation

docs/docker/DOCKER_QUICKSTART.md

@@ -141,6 +141,23 @@ environment variable on restart will not overwrite the stored password. Use
 the panel password reset flow, or recreate the Docker volumes for a fresh
 install.
 
+Keep the compose `INIT_ADMIN_*` / `DEFAULT_ADMIN_*` / `ADMIN_PASSWORD=${ADMIN_PASSWORD:-}`
+mappings uncommented — otherwise the host shell variable never reaches the
+container (issue #385).
+
+### Image architectures (`:dev` vs ARM)
+
+| Image | `:dev` platforms | Notes |
+|-------|------------------|-------|
+| `ghcr.io/unitronix/betterdesk` (AIO) | **amd64 only** | Multi-arch AIO on `:dev` often hits the GitHub Actions time limit |
+| `betterdesk-server` / `betterdesk-console` | amd64 + arm64 | Prefer [docker-compose.quick.yml](../../docker-compose.quick.yml) on ARM hosts |
+| `betterdesk` `latest` / release tags | amd64 + arm64 | Stable channel |
+
+On **linux/arm64**, use the split quick-start compose, build AIO locally from
+`docker-compose.single.yml`, or pin a multi-arch tip tag (e.g. `dev-arm`) when
+published. Do not expect a fresh `betterdesk:dev` pull to refresh ARM layers
+while AIO `:dev` remains amd64-only.
+
 ### PostgreSQL Instead of SQLite
 
 ```yaml

docs/docker/DOCKER_TROUBLESHOOTING.md

@@ -450,7 +450,9 @@ If no file is found yet, wait for first boot to finish and check `docker compose
 
 **Also common:** wiping only the `/opt/rustdesk` bind mount or volume while keeping `/app/data` (`console-data`). An old `auth.db` forces legacy panel authentication with a stale password hash, while bootstrap regenerates `.admin_credentials` on the rustesk volume. Current `:dev` images fail fast on this split state at container start.
 
-**Also common:** commenting out `INIT_ADMIN_PASS` / `DEFAULT_ADMIN_PASSWORD` in `docker-compose*.yml`. `ADMIN_PASSWORD=… docker compose up -d` on the host only passes the password into the container when those `${ADMIN_PASSWORD}` lines are present in the compose file.
+**Also common:** commenting out `INIT_ADMIN_PASS` / `DEFAULT_ADMIN_PASSWORD` / `ADMIN_PASSWORD` in `docker-compose*.yml`. `ADMIN_PASSWORD=… docker compose up -d` on the host only passes the password into the container when those `${ADMIN_PASSWORD}` lines are present in the compose file.
+
+**Also common on ARM64:** the all-in-one image tag `ghcr.io/unitronix/betterdesk:dev` is published as **amd64-only**. Hosts running `linux/arm64` keep an older cached AIO layer (or fail to refresh), while `betterdesk-server` / `betterdesk-console` stay multi-arch. Prefer [docker-compose.quick.yml](../../docker-compose.quick.yml), build AIO locally, or use a multi-arch tip tag such as `dev-arm` when published.
 
 **Workaround (existing broken install):**
 
@@ -466,7 +468,7 @@ ADMIN_PASSWORD='YourSecurePassword123' docker compose up -d
 
 Do not delete only the `/opt/rustdesk` bind mount while keeping `console-data`: that is not a clean reset. Do not use a credentials file to overwrite an existing user's password; use the normal password-reset procedure instead.
 
-**Fix:** Pull/rebuild current `:dev` images (or wait for the next GHCR tag). The split entrypoints elect one creator for the shared credentials file and both services reuse it. Setting `ADMIN_PASSWORD` before first start remains the deterministic option — keep the `INIT_ADMIN_*` / `DEFAULT_ADMIN_*` env mappings in your compose file.
+**Fix:** Pull/rebuild current `:dev` images (or wait for the next GHCR tag). On ARM64 prefer the split layout images. The split entrypoints elect one creator for the shared credentials file and both services reuse it. Setting `ADMIN_PASSWORD` before first start remains the deterministic option — keep the `INIT_ADMIN_*` / `DEFAULT_ADMIN_*` / `ADMIN_PASSWORD` env mappings in your compose file. Check `docker logs` for `Bootstrap: INIT_ADMIN_PASS/DEFAULT_ADMIN_PASSWORD set=yes|no` (password itself is never logged).
 
 ### Problem: `betterdesk-show-admin-credentials: executable file not found`