ai-librechat-english
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
| ai-librechat-english [2026/10/20 08:01] – created misa | ai-librechat-english [2026/10/20 11:21] (current) – misa | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Root³ Solutions LibreChat Deployment Guide ====== | ====== Root³ Solutions LibreChat Deployment Guide ====== | ||
| - | **Stack**: LibreChat + LM Studio (Qwen3 27B) + ComfyUI MCP | + | **Stack**: LibreChat + LM Studio (Qwen3 27B) + ComfyUI MCP + Admin Panel |
| **Host**: 192.168.1.203 — Nobara Linux, Podman (no Docker) | **Host**: 192.168.1.203 — Nobara Linux, Podman (no Docker) | ||
| - | **Deployed**: | + | **Deployed**: |
| - | **URL**: http:// | + | **URLs**: App http:// |
| + | **Account**: | ||
| ===== 1. Folder Structure ===== | ===== 1. Folder Structure ===== | ||
| - | All files live in one folder under the rootai home directory. No systemd units, no .env file required separately | + | One folder, everything inside it. All secrets |
| <code bash> | <code bash> | ||
| ~/ | ~/ | ||
| - | ├── compose.yaml | + | ├── compose.yaml |
| - | ├── librechat.yaml | + | ├── librechat.yaml |
| - | ├── boot-librechat.sh | + | ├── boot-librechat.sh |
| - | ├── .env | + | ├── .env # ALL secrets |
| - | ├── root_solutions_logo.svg | + | ├── root_solutions_logo.svg # Your logo — overwrites |
| - | ├── index.html | + | ├── index.html |
| - | └── custom.css | + | └── custom.css |
| </ | </ | ||
| - | ===== 2. compose.yaml (Full) ===== | + | ===== 2. compose.yaml (Complete) ===== |
| - | Two services | + | Three services: LibreChat API, MongoDB, and the separate Admin Panel [1]. No secrets in this file — only one ${VAR} reference for the panel session secret, which podman-compose expands from .env at create time (verified working). |
| <code yaml> | <code yaml> | ||
| Line 48: | Line 49: | ||
| - librechat-uploads:/ | - librechat-uploads:/ | ||
| - librechat-logs:/ | - librechat-logs:/ | ||
| - | # Environment file with all secrets | + | # All secrets/env — single source of truth is ./.env |
| - ./ | - ./ | ||
| environment: | environment: | ||
| Line 62: | Line 63: | ||
| volumes: | volumes: | ||
| - librechat-db-data:/ | - librechat-db-data:/ | ||
| + | restart: " | ||
| + | |||
| + | admin-panel: | ||
| + | image: registry.librechat.ai/ | ||
| + | container_name: | ||
| + | ports: | ||
| + | - " | ||
| + | depends_on: | ||
| + | - api | ||
| + | extra_hosts: | ||
| + | - " | ||
| + | volumes: | ||
| + | - ./ | ||
| + | environment: | ||
| + | - PORT=3000 | ||
| + | - SESSION_SECRET=${ADMIN_PANEL_SESSION_SECRET} | ||
| + | - API_SERVER_URL=http:// | ||
| + | - VITE_API_BASE_URL=http:// | ||
| restart: " | restart: " | ||
| Line 76: | Line 95: | ||
| **Key design decisions: | **Key design decisions: | ||
| - | * //restart: " | + | * //restart: " |
| - | * // | + | * // |
| - | * Named volumes for all durable data — safe to delete/recreate | + | * Named volumes for all durable data — deleting/recreating |
| - | * //docker.io/ | + | * Fully-qualified image names (docker.io/ |
| + | * Admin panel is a **separate URL** (:3090), not a tab inside the app — that is LibreChat' | ||
| - | ===== 3. .env File ===== | ||
| - | All secrets and auth settings go here. Mounted to ///app/.env// inside the container. This is how LibreChat reads its config in this build (the // | + | ===== 3. .env File (Complete — ALL Secrets Here) ===== |
| <code bash> | <code bash> | ||
| Line 94: | Line 112: | ||
| JWT_SECRET=super_secret_token_string_generation_12345 | JWT_SECRET=super_secret_token_string_generation_12345 | ||
| REFRESH_TOKEN_SECRET=super_secret_refresh_token_string_54321 | REFRESH_TOKEN_SECRET=super_secret_refresh_token_string_54321 | ||
| - | # THIS IS THE ONE THAT ACTUALLY WORKS FOR SIGN-IN ON THIS IMAGE BUILD: | + | # ⚠️ |
| JWT_REFRESH_SECRET=super_secret_refresh_token_string_54321 | JWT_REFRESH_SECRET=super_secret_refresh_token_string_54321 | ||
| + | ADMIN_PANEL_SESSION_SECRET=08513016b4e0f9fc9d3466f4d10e740efdf490c6d2fae7bc86536b2bb7fc5ea3 | ||
| + | ADMIN_PANEL_PORT=3090 | ||
| + | ADMIN_PANEL_URL=http:// | ||
| </ | </ | ||
| - | **⚠️ Critical note on JWT_REFRESH_SECRET: | + | **Notes:** |
| - | This image build' | + | * Mounted into BOTH the api and admin-panel containers |
| + | | ||
| + | * ADMIN_PANEL_PORT | ||
| - | ===== 4. librechat.yaml (Full) ===== | + | ===== 4. librechat.yaml (Complete) ===== |
| <code yaml> | <code yaml> | ||
| Line 122: | Line 145: | ||
| apiKey: " | apiKey: " | ||
| models: | models: | ||
| - | fetch: true # pulls live model list from LM Studio | + | fetch: true # live model list from LM Studio |
| default: [" | default: [" | ||
| titleConvo: true | titleConvo: true | ||
| Line 133: | Line 156: | ||
| args: | args: | ||
| - " | - " | ||
| - | - " | + | - " |
| - " | - " | ||
| - " | - " | ||
| Line 139: | Line 162: | ||
| **Notes:** | **Notes:** | ||
| - | * //baseURL// is the correct field name (not " | + | * //baseURL// is the correct field name (not " |
| - | * //fetch: true// | + | * //fetch: true// |
| - | * The original | + | * " |
| - | * First MCP call needs internet inside the container | + | * First MCP call needs internet inside the container |
| ===== 5. Logo Sizing (custom.css) ===== | ===== 5. Logo Sizing (custom.css) ===== | ||
| - | LibreChat renders logo.svg at a fixed small size in its built-in CSS and there is no config key to change it. The fix: patch index.html | + | LibreChat renders logo.svg at a fixed small size with no config key to change it. Fix: patched |
| ==== 5a. How it was set up ==== | ==== 5a. How it was set up ==== | ||
| <code bash> | <code bash> | ||
| - | # 1) Copy the real index.html out of the container (while | + | # 1) Copy the real index.html out of the container (while running) |
| podman exec librechat-app cat / | podman exec librechat-app cat / | ||
| - | |||
| # 2) Inject a link tag into < | # 2) Inject a link tag into < | ||
| sed -i ' | sed -i ' | ||
| - | + | # 3) The override | |
| - | # 3) Create the override | + | |
| cat > ~/ | cat > ~/ | ||
| img[src*=" | img[src*=" | ||
| Line 170: | Line 191: | ||
| </ | </ | ||
| - | ==== 5b. Tuning | + | ==== 5b. Tuning ==== |
| - | Edit // | + | Edit the px value in // |
| + | ⚠️ **After every LibreChat image update**, re-extract index.html from the fresh container and re-apply the sed line, then down/up once (logo patch would otherwise revert on new images). | ||
| - | ===== 6. boot-librechat.sh (Autostart Script) ===== | ||
| - | Runs from Nobara Login Scripts (System Settings → Autostart → Login Scripts). | + | ===== 6. boot-librechat.sh (Final Version) ===== |
| + | |||
| + | Runs via Nobara Login Scripts (System Settings → Autostart → Login Scripts). | ||
| <code bash> | <code bash> | ||
| Line 189: | Line 212: | ||
| MODEL=" | MODEL=" | ||
| - | # --- 1. LM Studio server up? ----------------------------------------- | + | # --- 1. LM Studio server up? ------------------------------------------ |
| if ! curl -s --connect-timeout 2 http:// | if ! curl -s --connect-timeout 2 http:// | ||
| echo "⏳ LM Studio not responding — starting server..." | echo "⏳ LM Studio not responding — starting server..." | ||
| Line 199: | Line 222: | ||
| fi | fi | ||
| - | # --- 2. Model loaded? (no-op if already in RAM) ---------------------- | + | # --- 2. Model loaded? (no-op if already in RAM) ------------------------ |
| echo "⏳ Loading model into LM Studio..." | echo "⏳ Loading model into LM Studio..." | ||
| lms load " | lms load " | ||
| sleep 5 | sleep 5 | ||
| - | # --- 3. Start LibreChat containers | + | # --- 3. Start all LibreChat containers --------------------------------- |
| if podman ps -a --filter " | if podman ps -a --filter " | ||
| echo "📦 Starting LibreChat containers..." | echo "📦 Starting LibreChat containers..." | ||
| - | podman start librechat-app librechat-db | + | podman start librechat-app librechat-db |
| else | else | ||
| echo " | echo " | ||
| Line 214: | Line 237: | ||
| fi | fi | ||
| - | # --- 4. Health check ------------------------------------------------- | + | # --- 4. Health check ----------------------------------------------------- |
| for i in $(seq 1 10); do | for i in $(seq 1 10); do | ||
| - | if curl -s --connect-timeout 2 http:// | + | if curl -s --connect-timeout 2 http:// |
| - | | + | |
| echo "✅ LibreChat API is up." | echo "✅ LibreChat API is up." | ||
| break | break | ||
| Line 228: | Line 250: | ||
| </ | </ | ||
| - | **Autostart setup (one-time): | + | **Autostart setup (one-time, already done):** |
| - | * Nobara System Settings → Autostart → **+ Add New** → Login Script | + | * Nobara System Settings → Autostart → + Add New → Login Script |
| - | * Select | + | |
| - | * Say **Yes** when asked to make it executable | + | |
| * To disable: trash the entry, or //rm ~/ | * To disable: trash the entry, or //rm ~/ | ||
| - | **Log file:** // | + | **Log file:** // |
| Line 240: | Line 260: | ||
| ^ Action ^ Command ^ | ^ Action ^ Command ^ | ||
| - | ^ Start stack (manual) ^ cd ~/librechat && | + | ^ Start stack (manual) ^ podman start librechat-app librechat-db |
| - | ^ Stop stack ^ podman stop librechat-app librechat-db ^ | + | ^ Stop stack ^ podman stop librechat-app librechat-db |
| - | ^ View logs (app) ^ podman logs --tail 100 librechat-app ^ | + | ^ Restart containers after changing yaml/env ^ cd ~/librechat && podman-compose --in-pod true down && podman-compose --in-pod true up -d ^ |
| - | ^ View logs (mongo) | + | ^ Update LibreChat image (keeps all data) ^ cd ~/librechat && podman-compose --in-pod true down && podman pull ghcr.io/ |
| + | ^ View app logs ^ podman logs --tail 100 librechat-app ^ | ||
| + | ^ View mongo logs ^ podman logs --tail 50 librechat-db | ||
| + | ^ View panel logs ^ podman logs --tail 50 librechat-admin | ||
| ^ View boot log ^ tail -f / | ^ View boot log ^ tail -f / | ||
| - | ^ Check pod status ^ podman pod ps ^ | + | ^ Pod status ^ podman pod ps ^ |
| - | ^ Update LibreChat image (keeps all data) ^ cd ~/ | + | ^ Remove stack, KEEP data ^ cd ~/librechat && podman-compose --in-pod true down ^ |
| - | ^ Remove stack, keep data ^ cd ~/librechat && podman-compose | + | |
| ^ Nuke everything including data ^ above + podman volume rm librechat-db-data librechat-images librechat-uploads librechat-logs ^ | ^ Nuke everything including data ^ above + podman volume rm librechat-db-data librechat-images librechat-uploads librechat-logs ^ | ||
| - | ^ Query users in DB ^ podman exec librechat-db mongosh --quiet --eval ' | + | ^ List all users + roles ^ podman exec librechat-db mongosh --quiet --eval ' |
| - | ^ Check LM Studio | + | ^ Check LM Studio live models |
| + | |||
| + | **Notes: | ||
| + | * " | ||
| + | * " | ||
| + | * All down/rm operations never touch named volumes — data is safe | ||
| ===== 8. Troubleshooting Log ===== | ===== 8. Troubleshooting Log ===== | ||
| - | ==== 8a. Sign-in | + | ==== 8a. Sign-in 500 " |
| - | **Cause: | + | **Cause: |
| - | **Fix: | + | **Fix:** JWT_REFRESH_SECRET=< |
| - | ==== 8b. " | + | ==== 8b. " |
| - | **Cause: | + | **Cause: |
| - | **Fix: | + | **Fix:** fully-qualified names in compose.yaml |
| - | ==== 8c. Code-interpreter image returns | + | ==== 8c. code-interpreter image 403 Forbidden ==== |
| - | **Cause: | + | **Cause:** ghcr.io/ |
| - | **Fix: | + | **Fix:** service |
| ==== 8d. Logo too small on login page ==== | ==== 8d. Logo too small on login page ==== | ||
| - | **Cause: | + | **Cause:** built-in CSS sizes logo.svg fixed; no interface |
| - | **Fix: | + | **Fix:** patched index.html |
| - | ==== 8e. podman-compose --pod flag not recognised | + | ==== 8e. podman-compose --pod not recognized |
| - | **Cause: | + | **Cause:** the dnf package |
| - | **Fix: | + | **Fix: |
| - | ==== 8f. " | + | ==== 8f. " |
| - | **Cause: | + | **Cause: |
| - | **Fix: | + | **Fix:** new conversation, select model explicitly first. ✅ Resolved. |
| + | ==== 8g. Admin panel image 403 on ghcr ==== | ||
| - | ===== 9. What Works / What's Verified ===== | + | **Cause:** ghcr.io/danny-avila/ |
| + | **Fix:** corrected image reference. ✅ Container runs, panel serves at :3090. | ||
| - | ^ Component ^ Status ^ Notes ^ | + | ==== 8h. Logs show "OpenID check failed: 500 .../openid/check" ==== |
| - | ^ Logo (big + centered) ^ ✅ Verified in browser ^ custom.css mount, 140px ^ | + | |
| - | ^ Auth (register + sign-in) ^ ✅ Working ^ JWT_REFRESH_SECRET fix applied ^ | + | |
| - | ^ LM Studio chat ^ ✅ "Hello!" | + | |
| - | ^ ComfyUI MCP server ^ ✅ " | + | |
| - | ^ Admin access ^ ✅ First registered user is admin [1] ^ Role dropdown = viewer scope, not account role ^ | + | |
| - | ^ Autostart (LLM first) ^ ✅ Nobara Login Script added ^ /var/log/ | + | |
| - | ^ Data persistence ^ ✅ Named volumes ^ Survives container recreation ^ | + | |
| - | ^ Podman Desktop grouping ^ ✅ pod_librechat, | + | |
| - | **Not yet tested:** ComfyUI image generation end-to-end from inside | + | **Cause:** known upstream bug — LibreChat |
| + | **Action:** none — ignore until an image update includes the fix. | ||
| - | ====== | + | ==== 8i. Admin panel login: form submits, nothing happens |
| - | </parameter> | + | ⚠️ **OPEN ITEM.** API logs show //[Login] [Login successful] [info@root3.de]// |
| - | </function> | + | **Status:** unresolved — next debugging step is the Network tab on :3090/login (failed request + status code) plus librechat-admin logs during an attempt. |
| - | </tool_call> | + | |
| + | |||
| + | ===== 9. Status Overview ===== | ||
| + | |||
| + | ^ Component ^ Status ^ Note ^ | ||
| + | ^ Logo (big + centered) ^ ✅ verified in browser ^ custom.css, 140px ^ | ||
| + | ^ Auth: register + sign-in ^ ✅ working ^ JWT_REFRESH_SECRET fix ^ | ||
| + | ^ LM Studio chat ^ ✅ " | ||
| + | ^ ComfyUI MCP server ^ ✅ " | ||
| + | ^ Admin account ^ ✅ info@root3.de (first user = ADMIN) ^ panel is separate URL :3090 ^ | ||
| + | ^ Admin panel service ^ ✅ running, serves :3090 ^ login still open (8i) ^ | ||
| + | ^ Autostart (LLM first) ^ ✅ Nobara Login Script ^ /var/ | ||
| + | ^ Data persistence ^ ✅ named volumes ^ survives recreation/ | ||
| + | ^ Podman Desktop grouping ^ ✅ pod_librechat, | ||
| + | | --- | --- | --- | | ||
| + | ^ ComfyUI image generation end-to-end ^ ⏳ not yet tested ^ last open functional test ^ | ||
| + | |||
| + | ====== | ||
ai-librechat-english.1792483311.txt.gz · Last modified: by misa
