feat(files): add Filestash player file share at files.${BASE_DOMAIN}

One shared login (htpasswd) for all players, writable. Config is rendered
from a template and mounted read-only, so git stays authoritative — the
admin console loads but cannot save, by design.

Filestash's OIDC/SAML middlewares are enterprise-only, so Keycloak SSO is
out; FILES_AUTH keeps htpasswd/passthrough switchable for later. Auth-off
(passthrough) is only valid once the host is off the public internet —
render-config.sh warns loudly when rendering it.

Three traps, all found by testing against the pinned image:
- the `local` backend is admin-gated: without LOCAL_BACKEND_SECRET in the
  connection params every login fails with "backend error - Not Allowed"
- the htpasswd plugin only accepts $2a$ bcrypt, so a $2y$ hash from
  `htpasswd -B` fails every login silently — use `openssl passwd -6`.
  render-config.sh rejects the wrong format rather than shipping it
- APPLICATION_URL/ADMIN_PASSWORD env make filestash rewrite config.json at
  boot, which fails on the :ro mount — both live in the rendered config

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -49,6 +49,52 @@ CADDY_HTTP_BIND=127.0.0.1
 # static site — it lives in ANOTHER repo. Bind-mounted read-only into caddy.
 DISTRIBUTION_WEB_ROOT=/home/oier/projects/mc-mods/ulicraft-group/ulicraft-distribution/dist
 
+# ── files.${BASE_DOMAIN} — Filestash player file share ────────────────
+# Screenshots / schematics / maps. ONE shared login for all players, writable.
+# Full design + gotchas: plan/20-files.md.
+
+# Host path holding the shared files. Keep it OUTSIDE the repo — guest-writable
+# data must not live in a git tree we `git pull` into.
+FILES_DATA_DIR=/srv/ulicraft-files
+
+# Literal mount flag for FILES_DATA_DIR: rw | ro. `ro` makes the share
+# read-only at the KERNEL, regardless of what the Filestash UI thinks. It is a
+# mount flag rather than a boolean because compose has no conditionals — the
+# value is substituted straight into the volume string.
+FILES_MOUNT_MODE=rw
+
+# Auth middleware (rendered into config.json by render-config.sh):
+#   htpasswd    one shared user/pass — the only internet-safe value
+#   passthrough NO LOGIN. Anyone reaching the vhost is in.
+#   none        alias of passthrough
+# passthrough/none on a WRITABLE, internet-reachable share is an open upload
+# relay (malware/phishing hosted on your domain, under your cert, with your
+# bandwidth — and a domain blocklisting would take auth. and the apex down
+# with it). Only set it once this host is unreachable from the internet.
+FILES_AUTH=htpasswd
+
+# The shared player credential (FILES_AUTH=htpasswd).
+#   FILES_PASSWORD_HASH:  openssl passwd -6 '<password>'
+# MUST be $6$ (sha512). The htpasswd plugin's bcrypt branch only accepts $2a$,
+# so a $2y$ hash from `htpasswd -B` fails EVERY login, silently.
+# render-config.sh rejects the wrong format rather than shipping it.
+FILES_USER=uli
+FILES_PASSWORD_HASH=
+
+# Filestash /admin console password — bcrypt, and /admin IS publicly exposed, so
+# use a 20+ char generated password. It is the only credential guarding config.
+#   docker run --rm caddy:alpine caddy hash-password --plaintext '<password>'
+FILES_ADMIN_PASSWORD_HASH=
+
+# Session key (openssl rand -hex 16). Must be non-empty: an empty secret_key
+# makes filestash rewrite config.json at boot, which fails on the :ro mount.
+FILES_SECRET_KEY=
+
+# Unlocks the local storage backend, which filestash admin-gates: it refuses to
+# init unless the connection params carry this secret. config.json supplies it
+# server-side; players never see it. openssl rand -hex 24.
+FILES_LOCAL_SECRET=
+
 # Only needed if using CurseForge-exclusive mods:
 # CF_API_KEY=your-curseforge-api-key
 
@@ -56,7 +102,7 @@ DISTRIBUTION_WEB_ROOT=/home/oier/projects/mc-mods/ulicraft-group/ulicraft-distri
 # Only needed to issue real TLS certs. DNS-01 needs no inbound ports.
 LE_EMAIL=you@example.com
 # space-separated subdomains; apex ${BASE_DOMAIN} is always included
-LE_SUBDOMAINS=auth distribution www avatar status
+LE_SUBDOMAINS=auth distribution www avatar status files
 # OVH API creds (DNS zone write). Create at https://eu.api.ovh.com/createToken/
 # OVH_CK can be blank on first run — acme.sh prints an auth URL, then paste it.
 OVH_END_POINT=ovh-eu