Update Docker_GUI_Managers/dockhand/README.md

Docker_GUI_Managers/dockhand/README.md

@@ -1,5 +1,6 @@
 Source: https://dockhand.pro/
 
+# Deploy
 Must have Docker installed: https://wiki.gabesville.com/books/docker/page/install-docker
 
 Run the docker command to install and run Dockhand:
@@ -9,7 +10,7 @@ Go to http://IPADDRESS:3000 to access
 
 If firewall(UFW) is enabled you may need to allow port 3000 (test first before creating the rule)
 
-For updating:
+# Updating
 1. CD to location you want the update script created
 2. `sudo nano update-dockhand.sh`
 3. Copypasta into file:
@@ -22,4 +23,153 @@ sleep 10s
 sudo docker run -d -p 3000:3000 --name dockhand --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /srv/docker/dockhand/dockhand_data:/app/data fnsys/dockhand:latest
 ```
 4. `sudo chmod u+x update-dockhand.sh`
-5. to run: `bash update-dockhand.sh`
+5. to run: `bash update-dockhand.sh`
+
+# How variables and secrets are handled:
+
+This document summarizes how environment variables and secrets behave when using **Dockerhand** to deploy a stack from a `compose.yaml` and `.env` file.
+
+---
+
+## Mental Model
+
+Dockerhand has **two different injection mechanisms**:
+
+| Type                | When injected            | Usable in `${VAR}` | Available in container |
+|---------------------|--------------------------|--------------------|------------------------|
+| **Variables**       | Before `docker compose`  | ✅ Yes             | ✅ Yes                 |
+| **Secrets**         | At container runtime     | ❌ No              | ✅ Yes                 |
+
+**Key takeaway:**
+> Dockerhand secrets do **not** participate in Docker Compose variable interpolation.
+
+---
+
+## `.env` File Usage
+
+Use `.env` for:
+- Non-secret defaults
+- Local development
+- Structural configuration
+
+Example:
+
+```env
+DB_USERNAME=postgres
+DB_HOSTNAME=database
+DB_PORT=5432
+DB_DATABASE_NAME=immich
+IMMICH_VERSION=release
+UPLOAD_LOCATION=/mnt/media
+
+
+⚠️ Do not rely on .env for secrets in production.
+
+❌ What Does NOT Work (Common Pitfall)
+
+This fails when DB_PASSWORD is marked as a secret in Dockerhand:
+
+environment:
+  DB_PASSWORD: ${DB_PASSWORD}
+
+
+Reason:
+
+Secrets are injected after Compose parsing
+
+${DB_PASSWORD} resolves to empty
+
+✅ Correct Pattern for Dockerhand Secrets
+Rule
+
+Never interpolate secrets with ${VAR}.
+Declare the variable name only.
+
+compose.yaml (Canonical Pattern)
+Application container (e.g. Immich)
+services:
+  immich-server:
+    env_file:
+      - .env
+    environment:
+      DB_USERNAME:
+      DB_PASSWORD:
+      DB_HOSTNAME:
+      DB_PORT:
+      DB_DATABASE_NAME:
+
+Database container (Postgres)
+services:
+  database:
+    environment:
+      POSTGRES_USER:
+      POSTGRES_PASSWORD:
+
+Dockerhand Configuration
+Variables (non-secret)
+DB_USERNAME=postgres
+POSTGRES_USER=postgres
+
+Secrets
+DB_PASSWORD=********
+POSTGRES_PASSWORD=********
+
+
+✔ Secrets are injected by name
+✔ Containers receive them at runtime
+✔ No ${VAR} expansion involved
+
+Why This Works
+
+Compose does not attempt interpolation
+
+Dockerhand injects secrets directly into container environments
+
+Applications read expected variables normally
+
+No accidental empty passwords
+
+No secret leakage via docker inspect
+
+Postgres-Specific Notes
+
+POSTGRES_PASSWORD is only used on initial DB creation
+
+Existing volumes require password changes via:
+
+ALTER USER postgres WITH PASSWORD 'newpassword';
+
+
+Authentication failures can be misleading when the app receives an empty password
+
+Debugging Checklist
+
+If authentication fails:
+
+Confirm secret is not interpolated (${VAR})
+
+Confirm variable name matches what the app expects
+
+Check inside container:
+
+env | grep PASSWORD
+
+
+Check Postgres logs for auth method (scram-sha-256)
+
+TL;DR
+
+.env = defaults & structure
+
+Dockerhand variables = safe overrides
+
+Dockerhand secrets = runtime injection only
+
+Never use ${VAR} for secrets
+
+Declare env var names and let Dockerhand fill them
+
+Final Rule to Remember
+
+If it’s marked as a secret in Dockerhand,
+Compose must never try to expand it.