[Docs][Enhancement]: Add warning about Redis caching librechat.yaml configuration

[eduardosanzb]

📝 Documentation Request: Warn users about Redis configuration caching

Problem Summary

When USE_REDIS=true is enabled, LibreChat caches the entire librechat.yaml configuration in Redis indefinitely without automatic invalidation. This causes significant deployment friction because:

1. Configuration changes in YAML don't take effect after service restart
2. Users must manually flush Redis to see config updates
3. This behavior is not documented in official Redis configuration docs
4. No architectural rationale has been provided for this design decision

Existing Issues & Discussions

This has been reported multiple times by users:

• Issue [Bug]: librechat.yaml file cached forever #4076 - "librechat.yaml file cached forever" (Sep 17, 2024)
• Issue [Question]: Librechat.yaml not working? #1498 - Maintainer confirms: "if you are using Redis, you would need to flush cache" (Jan 6, 2024)
• Discussion Librechat.yaml changes not taken into account #9725 - "Librechat.yaml changes not taken into account" (Sep 19, 2025) - Maintainer provides official workaround
• Issue [Bug]: flush-cache script does not respect Redis credentials #10081 - "flush-cache script does not respect Redis credentials" (Oct 10, 2025)

What Users Expect

Users expect that:

1. Editing librechat.yaml + restarting LibreChat = updated configuration
2. Configuration files should be read at startup, not cached indefinitely
3. There should be documentation warning about this behavior

Current State

✅ Redis docs exist at https://docs.librechat.ai/docs/configuration/redis
❌ No warning about config caching behavior
❌ No explanation that restart alone isn't sufficient
❌ No design rationale explaining why config files are cached

Proposed Documentation Update

Add a prominent warning section to /docs/configuration/redis documentation:

## ⚠️ Important: Configuration Caching Behavior

When Redis is enabled (`USE_REDIS=true`), LibreChat caches the entire `librechat.yaml` configuration in Redis on first load. **This cache is never automatically invalidated.**

### Impact:
- Changes to `librechat.yaml` **will NOT take effect** after application restart
- You **MUST manually flush Redis cache** after any configuration change
- Simply restarting containers or redeploying is **NOT sufficient**

### How to Apply Configuration Changes:

**Method 1: Flush All Redis Data** (⚠️ Clears all cached data including sessions)
`docker exec -it <redis-container-name> redis-cli FLUSHALL`

**Method 2: Use Flush Script** (⚠️ May have auth issues - see #10081)
`npm run flush-cache`

**Method 3: Disable Redis Temporarily** (For development/testing)
'''bash
# In .env file
USE_REDIS=false
'''

### Why This Happens:
LibreChat caches configuration in Redis for performance optimization across multiple instances. However, this creates deployment friction as configuration changes require manual cache invalidation.

### Development Workflow Recommendation:
For development environments where configuration changes frequently, consider:
1. Not enabling Redis (`USE_REDIS=false`)
2. Using `REDIS_KEY_PREFIX` to isolate dev cache from production
3. Scripting automatic cache flush in your deployment pipeline

---

Questions for Maintainers

1. What is the architectural rationale for caching static configuration files in Redis?
2. Is this performance-critical? (Does config get read frequently vs once per startup?)
3. Are there plans for automatic cache invalidation when YAML files change?
4. Would you accept a PR to make configuration caching optional via environment variable?
5. Would a file watcher that invalidates config cache on YAML modification be acceptable?

Current Redis Usage Context

Based on inspection, LibreChat stores these items in Redis:

• CONFIG_STORE:STARTUP_CONFIG - ❌ Shouldn't cache (read once at startup)
• CONFIG_STORE:ENDPOINT_CONFIG - ❌ Shouldn't cache (static config)
• CONFIG_STORE:MODELS_CONFIG - ❌ Shouldn't cache (static config)
• MCP::ServersRegistry::Status - ✅ Appropriate (runtime state)
• ROLES:* - ✅ Appropriate (user data)
• MODEL_QUERIES:* - ✅ Appropriate (response cache)

Industry Standard Practice

Redis is typically used for:

• ✅ Session storage
• ✅ Rate limiting
• ✅ Temporary cache with TTL
• ✅ Pub/sub messaging
• ✅ Job queues

Redis is not typically used for:

• ❌ Static configuration files (read at startup)
• ❌ Environment variables (never change at runtime)
• ❌ Indefinite caching without TTL