# 20 — Filestash (`files.${BASE_DOMAIN}`)

> Web file share for player media (screenshots, schematics, maps, guides).
> One [Filestash](https://github.com/mickael-kerjean/filestash) container behind
> caddy, **one shared username/password for everybody**, **writable**.
> Config is rendered read-only from a template, like drasl/nmsr.
>
> **Not** a backup browser, **not** a mod mirror. See "What goes in it".
>
> Everything below was verified against the real image (digest pinned in
> compose) and against the upstream source, not inferred from the docs — the
> docs omit most of it.

## Shape

```
Internet ── host nginx (TLS, LE cert for files.) ──► caddy ──► filestash:8334
                                                                  │
                                              ${FILES_DATA_DIR} ──┘ (bind mount)
```

| Thing | Value |
|---|---|
| Vhost | `files.${BASE_DOMAIN}` |
| Image | `machines/filestash` **pinned by digest** (upstream ships only `latest`) |
| Container port | `8334`, runs as **uid/gid 1000** (`filestash`) |
| Auth | htpasswd, **one shared account**, `FILES_USER` / `FILES_PASSWORD_HASH` |
| Access | read **+ write** for anyone with the password |
| Data | `${FILES_DATA_DIR}` on the host, **outside the repo** |
| State | named volume `filestash_state` → `/app/data/state` |
| Config | `filestash/config.json` rendered from `.tmpl`, mounted `:ro` |
| Backups | **none** — outside mc-backup's scope. Treat as disposable. |
| Quota | none — eyeballed |

## Decisions (settled — don't relitigate)

**Auth is htpasswd with one shared credential, not SSO.** Filestash's OIDC and
SAML middlewares are **enterprise-only**; the community build compiles in
`htpasswd`, `ldap`, `passthrough`, `wordpress`, `local` only (verified in
`server/plugin/index.go`). Keycloak was considered and dropped — it would need an
oauth2-proxy sidecar in front + `passthrough`. That path stays open but is not
built.

**One instance, everything behind the password.** No anonymous read tier.
Filestash's auth middleware is **global to the instance**, so "anonymous read +
authenticated write" is impossible in one container (that's the enterprise
RBAC). A two-instance split was designed and rejected as not worth it.

**`FILES_AUTH=none` is gated on the host being internal-only.** The off-switch
exists for when this server moves behind a LAN/VPN. **Do not set it while
`files.` is internet-reachable** — auth-off on a *writable* public share is an
open upload relay: someone parks malware or a phishing kit on your domain, under
your LE cert, and the abuse mail, the bandwidth, and a possible domain
blocklisting (which would take `auth.` and the apex down with it, breaking logins
and the launcher for every player) all land on you. `render-config.sh` prints a
loud warning when it renders this mode.

**Shared credential ⇒ no audit trail, no per-person revocation.** You will never
know who deleted a folder; rotating means re-telling everyone. Fine for a
friends' media share — but nothing here is backed up, so treat the share as
disposable and keep anything you'd miss elsewhere.

## What goes in it

| Content | Verdict |
|---|---|
| Screenshots, schematics, maps, guides | ✅ the point |
| World downloads / `./backups/*.tgz` | ❌ contains `playerdata/`, `stats/`, the full map — every player's inventory and coords, handed to anyone with the shared password |
| Mods / jars | ❌ redistribution; `distribution.${BASE_DOMAIN}` already serves the modset to launchers |

## `.env`

See `.env.example` for the annotated block. Summary:

| Var | What |
|---|---|
| `FILES_DATA_DIR` | host path of the share, outside the repo |
| `FILES_MOUNT_MODE` | literal mount flag, `rw` \| `ro` |
| `FILES_AUTH` | `htpasswd` \| `passthrough` \| `none` |
| `FILES_USER` | shared login name |
| `FILES_PASSWORD_HASH` | **`$6$`**, from `openssl passwd -6 '<pw>'` |
| `FILES_ADMIN_PASSWORD_HASH` | bcrypt, from `docker run --rm caddy:alpine caddy hash-password --plaintext '<pw>'` |
| `FILES_SECRET_KEY` | `openssl rand -hex 16`, must be non-empty |
| `FILES_LOCAL_SECRET` | `openssl rand -hex 24`, unlocks the local backend |
| `LE_SUBDOMAINS` | must include `files` |

`filestash/config.json` is **rendered and gitignored** — it holds every hash and
both secrets. Only the `.tmpl` is tracked.

## Deploy

```sh
tooling/render-config.sh                       # -> filestash/config.json (validates the JSON)
tooling/issue-letsencrypt.sh                   # picks up `files` from LE_SUBDOMAINS
tooling/render-nginx.sh --install              # adds the files. vhost + reloads nginx
mkdir -p "$FILES_DATA_DIR"                     # uid 1000 must be able to write it
docker compose up -d filestash caddy
```

Then add an Uptime Kuma HTTP monitor for `https://files.${BASE_DOMAIN}` (expect
`200` — the login page is a 200) and put it on the status page with the others.

## Gotchas (all of these were hit for real)

### The `local` backend is admin-gated — this is the one that wastes an evening
`plg_backend_local.Init()` **refuses to start** unless the connection params
carry `$LOCAL_BACKEND_SECRET` or the bcrypt admin password. Miss it and every
login dies at `backend error - Not Allowed`, which reads like a credentials
problem and isn't. `config.json`'s `attribute_mapping` injects the secret
server-side (Filestash calls this the "facade pattern"), so players never see it.
`FILES_LOCAL_SECRET` must be **identical** in the compose env and the rendered
config — `render-config.sh` renders both from the same var.

### `$2y$` bcrypt silently fails every login
The htpasswd plugin's bcrypt branch matches on the literal prefix **`$2a$`**.
`htpasswd -B` emits `$2y$`, which falls through to `return false` — so every
login fails with correct credentials and no useful log line. Use
**`openssl passwd -6`** (`$6$`, sha512) for `FILES_PASSWORD_HASH`.
`render-config.sh` hard-fails on a `$2y$`/`$2b$` hash rather than shipping a
config nobody can log into. (The *admin* password is checked by Go's bcrypt
directly, which does accept `$2y$` — but `caddy hash-password` gives `$2a$`
anyway, so just use that for both.)

### `general.host` is a BARE HOSTNAME — a scheme breaks the browser only
`"host": "files.ulicraft.net"`, **not** `"https://files.ulicraft.net"`, plus
`"force_ssl": true`. The SPA computes its redirect origin as
`(force_ssl ? "https://" : "http://") + host`, so a scheme in `host` yields
**`http://https://files.ulicraft.net`** and every client-side redirect dies —
the page loads, then silently fails to route anywhere.

The vicious part: the server-side Host check (`SecureOrigin`) **strips** the
scheme before comparing, so the server is perfectly happy. `curl /` returns 200,
the API answers, and the Uptime Kuma monitor stays green — **only real browsers
break**. Symptom in the log is a `POST /report?...msg=Redirecting to
http://https://...` line. Hit this on 2026-07-14; fixed in `config.json.tmpl`.

`force_ssl` only sets an HSTS header — it does **not** redirect, so it can't loop
behind the nginx→caddy (plain http) hop. It must be `true` or the SPA builds
`http://` origins on an https page.

### `general.host` must also match the incoming `Host` header
Filestash blocks every non-`/admin/` request whose `Host` differs from
`general.host`, with *"only traffic from X is allowed"* — a 403 that looks like
an auth failure. nginx forwards the original Host and caddy passes it through —
don't rewrite it anywhere.

### The login form only renders at `?action=redirect`
`GET /api/session/auth/` renders the htpasswd form **only** when
`action=redirect` is present; any other request falls through to the credential
check, fails with empty creds, and 303s back to `?action=redirect`. So the real
form URL is `/api/session/auth/?action=redirect&label=files`. A bare
`/api/session/auth/?label=files` returning a 303 is **normal**, not a bug.

### `config.json` is a single-file bind mount → stale inode
Same shape as the caddy `conf.d` gotcha. The mount pins the **inode**, so
re-rendering (or a `git pull`) writes a *new* file while the container keeps
reading the *old* one.

**After re-rendering: `docker compose up -d --force-recreate filestash`.**
`restart` is not enough. Rotating the shared password needs a recreate too.

### Don't set `APPLICATION_URL` or `ADMIN_PASSWORD` env
Either one makes Filestash **rewrite `config.json` at boot**, which fails against
the `:ro` mount. Both live in the rendered config instead (`general.host` /
`auth.admin`). `general.secret_key` must likewise be non-empty, or Filestash
generates one and tries to save that. With all three set in the file, Filestash
never attempts a boot write and the `:ro` mount is clean — you get one harmless
`cannot chmod config file` WARN in the log, and nothing else.

### The admin console cannot save
`/admin` loads and its login works, but `config.json` is `:ro`, so every save
silently fails. That's the deliberate trade for keeping git authoritative
(drasl/nmsr never write their configs; Filestash does, which is exactly why it
needs pinning). To change config: edit the `.tmpl`, re-render, recreate. To
re-derive the schema after an upstream upgrade: run the image locally against a
*writable* state volume, click it into shape, `docker cp` the result out.

### The API needs `X-Requested-With: XmlHttpRequest`
The SPA sends it; anything else (curl, a naive monitor) trips intrusion
detection and gets a 403 that looks like an auth bug. Only matters when probing
by hand — the Kuma monitor hits `/`, which is fine.

### Disk is the shared failure domain
`FILES_DATA_DIR` grows without a quota, driven by whoever has the password. A
full disk on `cochi` does not just break `files.` — it takes **Minecraft, Drasl,
and mc-backup** down with it. Eyeballing is the accepted plan. Revisit (quota,
separate partition, or a Kuma disk monitor) if the share sees real use.

### Pinned digest, not `latest`
`machines/filestash` publishes essentially only `latest`. Unpinned, any
`docker compose pull` silently ships a new upstream build of an internet-facing,
writable file manager. Pin the digest; upgrade deliberately — same discipline as
`NEOFORGE_VERSION`.

## Deferred

- **Keycloak SSO** — needs oauth2-proxy + `FILES_AUTH=passthrough`. Not built.
- **Anonymous access** (`FILES_AUTH=none`) — only once the host is internal-only.
- **Landing page link** — deliberately none on day one; `plan/18-landing-rework.md`
  is mid-rework, so revisit with WS5 (footer) rather than merging into a moving
  design.
- **Per-user accounts / roles** — htpasswd RBAC is enterprise-only.
- **Backups / quota** — none.