Updated backend

.env.example

@@ -1,5 +1,69 @@
 # Copy this file to .env and fill in your own values.
 # Nothing here is a real credential.
+#
+# The host-side values below are for running the backend directly with uvicorn
+# (python run_project.py). When the backend runs INSIDE Docker via the root
+# docker-compose.yml, four of them are overridden by compose and you do not
+# need to change them here:
+#
+#   DB_HOST         -> postgres      (service name)
+#   DB_PORT         -> 5432
+#   DB_PASSWORD     -> POSTGRES_PASSWORD from the root .env
+#   OLLAMA_BASE_URL -> http://ollama:11434
+#
+# The reason is worth internalising: inside a container, `localhost` is the
+# container itself, not the host and not a sibling container. A container-bound
+# localhost URL points the backend at its own empty ports. Containers reach
+# each other by service name over the compose network instead.
+
+# --- Authentication (REQUIRED) -------------------------------------------
+# The backend will not start without these while AUTH_ENABLED=true. Generate
+# all four lines, plus sign-in passwords, with:
+#
+#     python scripts/make_auth_secrets.py
+#
+# They guard the 18 write/compute endpoints - catalog generation, ML training,
+# the upload endpoints and chat. CORS is not a substitute: browsers enforce it,
+# curl ignores it entirely.
+#
+# AUTH_ENABLED=false turns every guard off and makes the whole API open again.
+# It exists so a fresh checkout runs before you have generated secrets. Never
+# set it false on a host reachable from the internet.
+AUTH_ENABLED=true
+
+# Signs access tokens. Changing it signs everybody out, which is how you revoke
+# every issued token at once. Use a DIFFERENT value in production from the one
+# on your laptop - a secret that has been on a dev machine is not a secret.
+AUTH_SECRET_KEY=
+
+# Only PBKDF2 digests are stored, never passwords. `make_auth_secrets.py`
+# prints the password once and the hash to paste here; it cannot be reversed,
+# so rerun the script to change a password.
+AUTH_ADMIN_USERNAME=admin
+AUTH_ADMIN_PASSWORD_HASH=
+AUTH_USER_USERNAME=user
+AUTH_USER_PASSWORD_HASH=
+
+# Token lifetime in minutes. 12h by default: one sign-in per working day, and
+# a leaked token expires by itself.
+AUTH_TOKEN_TTL_MINUTES=720
+
+# Failed-login throttle, per username+IP. Stops the login endpoint being an
+# unlimited password oracle once it is on the internet.
+AUTH_MAX_LOGIN_ATTEMPTS=10
+AUTH_LOCKOUT_SECONDS=300
+
+# Machine consumers of api.<domain> - scripts, partner integrations, your own
+# backends. Format: name:role:secret, comma-separated, role is admin or user.
+# Callers send the secret as an X-API-Key header.
+#
+# One entry per consumer, always: a shared key cannot be revoked for one caller
+# without breaking every other. Mint them with:
+#   python scripts/make_auth_secrets.py --api-key partner-x:user
+#
+# Leave empty if only the web app calls the API - it signs in through
+# /api/auth/login instead, and a key nobody needs is only risk.
+API_KEYS=
 
 USE_OLLAMA=true
 OLLAMA_BASE_URL=http://localhost:11434