fix(6244): the instance keeps its own SECRET_KEY in /data, and docker-compose.yml is the compose users deploy from

With no SECRET_KEY set, Grimoire fell back to a fixed placeholder. The
quickstart compose substituted change-me-in-production, so the README's
own update step (pull, up -d) recreated the container on that placeholder,
and every credential sealed under the key the user started with stopped
opening.

- config: with neither SECRET_KEY nor SECRET_KEY_FILE, the first start
  writes a random key to DATA_DIR/secret_key (mode 0600, published with a
  hard link so concurrent starts agree), and later starts read it back.
  An explicit key wins and leaves the file alone. A missing
  SECRET_KEY_FILE or an empty key file stops the start instead of
  switching keys. With no data directory (a run outside the container)
  the process gets a temporary key and says so.
- app: warns on a public placeholder key, on a temporary key, and when
  /data is not a mounted volume.
- Dockerfile creates /data.
- docker-compose.yml is now the deploy compose (published image, both
  volumes, nothing to set). The build-from-source compose is
  docker-compose.dev.yml, and docker-compose.quickstart.yml is gone. The
  Swarm stack file gains the /data volume and keeps its explicit key,
  because a Swarm can move the app away from a node-local volume.
- README: a Deploy section with the compose inline, SECRET_KEY optional,
  "keep both volumes", and updates that keep the key. A test holds the
  README's copy equal to the file.
- Installs that ran on the change-me-in-production placeholder get a key
  of their own on the new compose; Settings then asks once for saved
  forge tokens and the backup secret.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/architecture.md

@@ -74,7 +74,7 @@ Every database wait on startup has a deadline. Migrations wait for the database
 - **OIDC** single sign-on with PKCE, optionally replacing local logins ([SSO / OAuth](sso-oauth.md)).
 - **Rate limits** on register, login and forgot-password, per client IP (`TRUST_PROXY_HEADERS` reads the IP from the proxy's headers).
 
-Credentials Grimoire stores for outside services (forge tokens, the backup destination's S3 secret) are sealed under a key derived from `SECRET_KEY`.
+Credentials Grimoire stores for outside services (forge tokens, the backup destination's S3 secret) are sealed under a key derived from `SECRET_KEY`, which the instance makes on first start and keeps in `/data/secret_key` unless one is set.
 
 ## Repository layout
 

docs/backups.md

@@ -31,7 +31,8 @@ differently. It does **not** hold:
 - **Credentials:** API keys and forge connections. After a restore, issue new
   API keys and add forge connections again. (Forge tokens are also sealed under
   `SECRET_KEY` in the database itself, so a copy of the database doesn't carry
-  them in readable form either.)
+  them in readable form either. The key lives in `/data/secret_key`, outside
+  the database.)
 - **Logs and notifications.**
 - **The backup destination's own S3 secret.**
 

docs/configuration.md

@@ -11,7 +11,8 @@ Any variable marked *secret* can also be read from a file: set `<NAME>_FILE` to
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `DATABASE_URL` *(secret)* | `postgresql+asyncpg://grimoire:grimoire@localhost:5432/grimoire` | PostgreSQL connection string, using the `asyncpg` driver |
-| `SECRET_KEY` *(secret)* | `dev-secret-change-me` | Signs sessions and seals stored credentials. Set it before first use and keep it (see below) |
+| `SECRET_KEY` *(secret)* | kept in `DATA_DIR` | Signs sessions and seals stored credentials. Unset, the instance makes its own on first start and keeps it in `DATA_DIR/secret_key`. Set it only to manage the key yourself; it wins over the kept one (see below) |
+| `DATA_DIR` | `/data` | Where the instance keeps its own `SECRET_KEY`. Mount a volume here |
 | `BASE_URL` | `http://localhost:5000` | Public URL, used in email links and OIDC redirects |
 | `SECURE_COOKIES` | `false` | `true` when Grimoire is served over HTTPS |
 | `TRUST_PROXY_HEADERS` | `false` | `true` behind a reverse proxy, to read the client IP from `X-Forwarded-For` / `X-Real-IP` |
@@ -56,27 +57,27 @@ Admins can set SMTP in **Settings**; these are the defaults until they do.
 
 ## Running it
 
-### Quick start
+### Docker Compose
 
-[`docker-compose.quickstart.yml`](../docker-compose.quickstart.yml) runs the published image with its own database:
+[`docker-compose.yml`](../docker-compose.yml) runs the published image with its own database, and needs nothing set:
 
 ```bash
-SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))') \
-  docker compose -f docker-compose.quickstart.yml up -d
+docker compose up -d
 ```
 
 Open `http://localhost:5000`. The first account registered becomes the admin; after that, registration stays closed until an admin opens it in Settings or sends an invite.
 
+Update with `docker compose pull && docker compose up -d`. The key and the data stay in their volumes.
+
 ### From source
 
 ```bash
-cp .env.example .env   # then set SECRET_KEY
-docker compose up --build
+docker compose -f docker-compose.dev.yml up --build
 ```
 
 ### Docker Swarm
 
-[`docker-compose.prod.yml`](../docker-compose.prod.yml) is a stack file: the app and database on a private overlay network, with `SECURE_COOKIES` and `TRUST_PROXY_HEADERS` on. Provide `DB_PASSWORD` and `SECRET_KEY` in the environment:
+[`docker-compose.prod.yml`](../docker-compose.prod.yml) is a stack file: the app and database on a private overlay network, with `SECURE_COOKIES` and `TRUST_PROXY_HEADERS` on. A Swarm can move the app to another node, away from a node-local `/data` volume, so the stack sets its own key: provide `DB_PASSWORD` and `SECRET_KEY` in the environment (or mount a Docker secret and set `SECRET_KEY_FILE`):
 
 ```bash
 DB_PASSWORD=... SECRET_KEY=... docker stack deploy -c docker-compose.prod.yml grimoire
@@ -89,9 +90,9 @@ The shipped files leave out healthchecks and restart policies on purpose. The ap
 ### Volumes
 
 - **Database** (`pgdata`): everything Grimoire stores.
-- **App data** (`/data`): the embedding model cache and diagnostics. Losing it costs a re-download, nothing else.
+- **App data** (`/data`): the instance's own `SECRET_KEY`, the embedding model cache and diagnostics. Losing it costs the key: Settings then asks for saved forge tokens and the backup secret again, and the model downloads again.
 
-Back up the database with **Settings → Data → Scheduled backups** ([Backups](backups.md)).
+Back up the database with **Settings → Data → Scheduled backups** ([Backups](backups.md)). A database backup doesn't carry the key; to move sealed credentials to a new instance, copy `/data/secret_key` with it.
 
 ## Behind a reverse proxy
 
@@ -115,7 +116,7 @@ With `TRUST_PROXY_HEADERS=true`, make sure the proxy replaces any `X-Forwarded-F
 
 ## Security checklist
 
-- **Set a strong `SECRET_KEY`, and keep it.** Forge tokens and the backup destination's S3 secret are sealed under a key derived from it, so a copy of the database alone can't read them. If the key changes (say, a restore onto an instance with a different key), Settings marks those credentials and asks for them again; nothing else breaks. The app logs a warning at startup while the default key is in use, and refuses to start with it when `SECURE_COOKIES=true`.
+- **Keep the key.** Forge tokens and the backup destination's S3 secret are sealed under a key derived from `SECRET_KEY`, so a copy of the database alone can't read them. Unset, the instance makes a random key and keeps it in `/data/secret_key`, readable by its owner only; keep that volume. If the key changes (say, a restore onto an instance with a different key), Settings marks those credentials and asks for them again; nothing else breaks. The app warns at startup when `SECRET_KEY` is a public placeholder or `/data` is not a mounted volume, and refuses to start with `dev-secret-change-me` when `SECURE_COOKIES=true`.
 - **`SECURE_COOKIES=true`** whenever Grimoire is served over HTTPS.
 - **Registration** is open only for the first account. Invite people, or open it briefly from Settings.
 - **Signing everyone else out**: changing a password ends that user's other sessions; Settings → Account has a button for it too.

docs/development.md

@@ -3,9 +3,9 @@
 ## Running it
 
 ```bash
-docker compose up --build          # app + PostgreSQL at http://localhost:5000
-docker compose up --build app      # rebuild after a change
-docker compose down -v             # stop and wipe the database
+docker compose -f docker-compose.dev.yml up --build       # app + PostgreSQL at http://localhost:5000
+docker compose -f docker-compose.dev.yml up --build app   # rebuild after a change
+docker compose -f docker-compose.dev.yml down -v          # stop and wipe the database
 ```
 
 The image builds the frontend, so a frontend change needs a rebuild too. For quicker frontend work, run Vite against the running app; it proxies `/api` to port 5000:
@@ -32,7 +32,7 @@ Unit tests run without a database. Tests marked `integration` need a real Postgr
 The container runs `alembic upgrade head` on every start, after waiting for the database to accept connections.
 
 ```bash
-docker compose exec app alembic revision -m "short_description"
+docker compose -f docker-compose.dev.yml exec app alembic revision -m "short_description"
 ```
 
 - Number revisions sequentially (`0123_...`). Revision ids must fit in 32 characters, the width of `alembic_version.version_num`.