diff --git a/.env.example b/.env.example
index e7c48f3..263306c 100644
--- a/.env.example
+++ b/.env.example
@@ -49,3 +49,14 @@ RATE_LIMIT_PER_MINUTE=120
 MEDIA_ROOT=./media
 MEDIA_URL_PREFIX=/media
 ARTWORK_DOWNLOAD_MAX_BYTES=15728640
+
+# --- Production only (docker-compose.prod.yml) ---
+# Not used by docker-compose.yml (local dev) or the app itself directly --
+# only interpolated into the postgres/pgbouncer service definitions.
+# Generate POSTGRES_PASSWORD with a URL-safe generator, not `openssl rand
+# -base64`: base64 output can contain `/+=`, which breaks pgbouncer's (and
+# any DATABASE_URL parser's) naive URL parsing.
+POSTGRES_USER=aurora
+# python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+POSTGRES_PASSWORD=changeme-generate-a-real-password
+POSTGRES_DB=aurora_core
diff --git a/README.md b/README.md
index 7cfaa9b..91082c5 100644
--- a/README.md
+++ b/README.md
@@ -184,8 +184,9 @@ once the subdomain exists and DNS resolves).
    either cPanel/WHM's Application Manager if available, or a custom
    Apache/LiteSpeed vhost include (`ProxyPass`/`ProxyPassReverse` for
    Apache; LiteSpeed's External App + rewrite rule for LiteSpeed).
-3. **`.env`** on the server (never committed), beyond the base vars in
-   `.env.example`:
+3. **`.env`** on the server (never committed) — fill in every value in
+   `.env.example`, including the "Production only" section at the bottom
+   (`POSTGRES_USER`/`PASSWORD`/`DB`), plus:
 
    ```bash
    CORS_ORIGINS=https://www.amdbs.net  # must include the frontend's real origin
diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
index 977aa9a..3423bde 100644
--- a/docker-compose.prod.yml
+++ b/docker-compose.prod.yml
@@ -39,6 +39,10 @@ services:
       POOL_MODE: transaction
       MAX_CLIENT_CONN: "1000"
       DEFAULT_POOL_SIZE: "25"
+      # postgres:17-alpine defaults password_encryption to scram-sha-256;
+      # pgbouncer defaults auth_type to md5, which then fails every
+      # connection with "wrong password type" against a scram-only server.
+      AUTH_TYPE: scram-sha-256
     depends_on:
       postgres:
         condition: service_healthy