docs(apps): expand configuration and integration guides

openwebui/README.md

@@ -1,40 +1,42 @@
-# Open WebUI — Interfaz web para LLMs
+# Open WebUI
 
-Open WebUI conectado al stack de Ollama. Expone una UI de chat accesible en `chat.sherlockhomeless.net`, protegida por CrowdSec. Tiene su propio sistema de login, no usa Authentik.
+Interfaz de chat para los modelos publicados por LiteLLM. Ollama está deshabilitado explícitamente; este despliegue usa únicamente la API compatible con OpenAI.
 
-## Prerequisitos
+## Arquitectura
 
-- Stack **Ollama** desplegado y en la red `proxy`
-- DNS + Tunnel registrado para `chat.sherlockhomeless.net`
+Open WebUI se une a `proxy`, desde donde Traefik lo publica y puede alcanzar `litellm:4000`. Los chats, usuarios y ajustes se guardan en `OPENWEBUI_DATA_PATH`.
 
-```bash
-cd cloudflared
-./add-domain.sh chat
-```
+## Configuración
+
+| Variable | Uso |
+| --- | --- |
+| `OPENAI_API_BASE_URL` | `http://litellm:4000/v1` para tráfico interno |
+| `OPENAI_API_KEY` | Valor de `LITELLM_MASTER_KEY`, no una credencial de Codex |
+| `WEBUI_SECRET_KEY` | Firma sesiones; debe ser aleatoria y estable |
+| `OPENWEBUI_DOMAIN`, `WEBUI_URL` | URL pública detrás de Traefik |
+| `ENABLE_SIGNUP` | Debe desactivarse salvo durante un alta controlada |
+| `ENABLE_LOGIN_FORM` | Mantiene o elimina el login local según la estrategia SSO |
+| `WEBUI_AUTH_TRUSTED_*_HEADER` | Cabeceras de identidad entregadas por el proxy autenticado |
+
+Las cabeceras de usuario sólo son seguras si Open WebUI no puede alcanzarse evitando Traefik y si el proxy elimina cualquier cabecera equivalente enviada por el cliente. `WEBUI_SECRET_KEY` no debe cambiarse en cada recreación porque invalidaría sesiones.
+
+## Relación con Codex
+
+Open WebUI nunca monta ni lee `auth.json`. Envía una petición OpenAI-compatible a LiteLLM; LiteLLM valida su clave, selecciona el alias y, si corresponde, usa su proveedor Codex. Esto limita la exposición del refresh token a un único contenedor.
 
 ## Despliegue
 
 ```bash
-mkdir -p /opt/openwebui/data
-# Editar openwebui/.env: cambiar WEBUI_SECRET_KEY por un valor aleatorio
-openssl rand -hex 32
-docker compose --env-file openwebui/.env -f openwebui/docker-compose.yml up -d
+cd openwebui
+docker compose --env-file .env config
+docker compose --env-file .env up -d
 ```
 
-## Primer acceso
+## Verificación
 
-La primera cuenta registrada se convierte en administrador. Después de crearla, pon `ENABLE_SIGNUP=false` en `.env` y redespliega para bloquear nuevos registros.
+```bash
+docker compose --env-file .env ps
+docker compose --env-file .env logs -f openwebui
+```
 
-## Conexión con Ollama
-
-OpenWebUI se conecta a Ollama via red interna Docker: `http://ollama:11434`.  
-Ambos contenedores deben estar en la red `proxy`.
-
-## Variables clave
-
-| Variable | Descripción |
-|----------|-------------|
-| `WEBUI_SECRET_KEY` | Clave para firmar sesiones — generar con `openssl rand -hex 32` |
-| `OLLAMA_BASE_URL` | URL interna de Ollama (`http://ollama:11434`) |
-| `ENABLE_SIGNUP` | `false` para bloquear nuevos registros |
-| `WEBUI_NAME` | Nombre mostrado en la interfaz |
+Si no aparecen modelos, prueba primero `/v1/models` contra LiteLLM con la misma clave. Si los modelos aparecen pero fallan sólo los alias Codex, revisa el montaje y renovación de `auth.json` en LiteLLM.