docs: document LOG_DIR mounted log files and rotation

Author: sauin

README.md

@@ -46,6 +46,11 @@ Per-service config files live under `config/`:
 
 Local defaults: `config/api.local.yaml`, `config/indexer.local.yaml`. Override at runtime with `APP_CONFIG=/path/to/file.yaml`.
 
+Logging is environment-driven: `RUST_LOG` sets verbosity, and `LOG_DIR`
+(optional) makes each service also write rotated log files into a directory —
+the Compose deployment bind-mounts these to `./logs/<service>`. See
+[docs/deployment.md](docs/deployment.md#logs).
+
 Secrets and environment-specific values live in `.env`:
 
 ```sh

docs/deployment.md

@@ -252,8 +252,10 @@ api only:
 ## Step 4 — Compose override, build, and run
 
 The base `docker-compose.yml` mounts `./config` into each container read-only
-(`/app/config`) and defaults `APP_CONFIG` to the `*.local.yaml` files. Add an
-override that points `APP_CONFIG` at your own files — mirroring how
+(`/app/config`), bind-mounts a per-service host log directory
+(`./logs/api`, `./logs/indexer` → `/app/logs`) with `LOG_DIR=/app/logs` set,
+and defaults `APP_CONFIG` to the `*.local.yaml` files. Add an override that
+points `APP_CONFIG` at your own files — mirroring how
 `docker-compose.stage.yml` selects the Supabase configs.
 
 Create `docker-compose.prod.yml`:
@@ -327,12 +329,30 @@ docker compose -f docker-compose.yml -f docker-compose.prod.yml kill -s SIGUSR1
 
 ### Logs
 
+Each service writes to **both** stdout and a host-mounted directory. The base
+`docker-compose.yml` bind-mounts `./logs/api` and `./logs/indexer` (on the host)
+to `/app/logs` (in each container) and sets `LOG_DIR=/app/logs`. With `LOG_DIR`
+set, the service writes daily-rotated, human-readable files named
+`<service>.log.<YYYY-MM-DD>` into that directory, keeping at most `LOG_MAX_FILES`
+of them (default 14):
+
 ```sh
+# tail the live stdout stream (unchanged)
 docker compose -f docker-compose.yml -f docker-compose.prod.yml logs -f api indexer
+
+# the persisted files on the host (survive container removal / redeploy)
+tail -f logs/api/api.log.*
+ls -1 logs/indexer/
 ```
 
-Log verbosity is controlled by `RUST_LOG` (set in the override) and
-`app.log_level` in config.
+Notes:
+
+- The containers run as `root`, so files under `logs/` are root-owned — use
+  `sudo` to read/rotate them as a non-root user.
+- `LOG_DIR` and `LOG_MAX_FILES` are environment variables (there is no YAML
+  config key). Unset `LOG_DIR` to disable file logging and keep stdout only.
+- Verbosity is still controlled by `RUST_LOG` (set in the override) and
+  `app.log_level` in config; the same filter applies to stdout and files.
 
 ### Upgrades
 

services/api/README.md

@@ -35,6 +35,11 @@ Config sections:
   `page_size` defaults to 100 and may be omitted; it is used by the
   indexer's paginated fetches but not by the API tier.
 
+Logging is configured by environment variables, not YAML: `RUST_LOG` sets the
+filter (default `info`), and `LOG_DIR` (optional) makes the service additionally
+write daily-rotated `api.log.<date>` files into that directory, retaining
+`LOG_MAX_FILES` of them (default 14). See [docs/deployment.md](../../docs/deployment.md#logs).
+
 The `auth.kek_hex` field is the 32-byte master key used to encrypt
 `api_secret` and `pn_seckey` at rest. `config/api.local.yaml` ships a
 shared dev value; stage and prod configs carry their own KEKs assembled

services/indexer/README.md

@@ -25,6 +25,11 @@ Config sections:
 - `graphql`: gateway endpoint, page size, request timeout.
 - `indexer`: polling/reconciliation/reprojection intervals and ignored addresses.
 
+Logging is configured by environment variables, not YAML: `RUST_LOG` sets the
+filter (default `info`), and `LOG_DIR` (optional) makes the service additionally
+write daily-rotated `indexer.log.<date>` files into that directory, retaining
+`LOG_MAX_FILES` of them (default 14). See [docs/deployment.md](../../docs/deployment.md#logs).
+
 ## Database
 
 The indexer applies SQL migrations from `migrations/` on startup. Column and