feat(librechat): install librechat
This commit is contained in:
Masaki Yatsu
227
librechat/README.md
Normal file
227
librechat/README.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# LibreChat
|
||||
|
||||
Web-based chat interface for interacting with LLMs:
|
||||
|
||||
- **Multi-Model Support**: Connect to Ollama, OpenAI, Anthropic, and custom endpoints
|
||||
- **MCP Integration**: Model Context Protocol for web search and external tools
|
||||
- **Keycloak Authentication**: OAuth2/OIDC integration for user management
|
||||
- **Conversation History**: MongoDB-backed chat history with search via Meilisearch
|
||||
- **Persistent Storage**: User-uploaded images stored persistently
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Keycloak](../keycloak/README.md) for OIDC authentication
|
||||
- [Vault](../vault/README.md) for secrets management
|
||||
- [Ollama](../ollama/README.md) for local LLM inference (optional)
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
just librechat::install
|
||||
```
|
||||
|
||||
During installation, you will be prompted for:
|
||||
|
||||
- **LibreChat host**: FQDN for LibreChat (e.g., `chat.example.com`)
|
||||
- **Keycloak host**: FQDN for Keycloak (e.g., `auth.example.com`)
|
||||
- **Tavily MCP**: Enable web search via Tavily API (requires API key)
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
| -------- | ------- | ----------- |
|
||||
| `LIBRECHAT_NAMESPACE` | `librechat` | Kubernetes namespace |
|
||||
| `LIBRECHAT_CHART_VERSION` | `1.9.3` | Helm chart version |
|
||||
| `LIBRECHAT_HOST` | (prompt) | LibreChat FQDN |
|
||||
| `LIBRECHAT_OIDC_CLIENT_ID` | `librechat` | Keycloak client ID |
|
||||
| `KEYCLOAK_HOST` | (prompt) | Keycloak FQDN |
|
||||
| `KEYCLOAK_REALM` | `buunstack` | Keycloak realm |
|
||||
| `OLLAMA_HOST` | `ollama.ollama.svc.cluster.local` | Ollama service host |
|
||||
| `TAVILY_MCP_ENABLED` | (prompt) | Enable Tavily MCP (`true`/`false`) |
|
||||
|
||||
### Example with Environment Variables
|
||||
|
||||
```bash
|
||||
LIBRECHAT_HOST=chat.example.com \
|
||||
KEYCLOAK_HOST=auth.example.com \
|
||||
TAVILY_MCP_ENABLED=true \
|
||||
just librechat::install
|
||||
```
|
||||
|
||||
## Ollama Integration
|
||||
|
||||
LibreChat automatically connects to Ollama using the internal Kubernetes service
|
||||
URL. The default models configured are:
|
||||
|
||||
- `qwen3:8b`
|
||||
- `deepseek-r1:8b`
|
||||
|
||||
LibreChat fetches the available model list from Ollama, so any models you pull
|
||||
will be available.
|
||||
|
||||
## MCP (Model Context Protocol)
|
||||
|
||||
LibreChat supports MCP servers for extending model capabilities with external tools.
|
||||
|
||||
### Tavily Web Search
|
||||
|
||||
When `TAVILY_MCP_ENABLED=true`, LibreChat can search the web using Tavily API:
|
||||
|
||||
1. Get a Tavily API key from [tavily.com](https://tavily.com/)
|
||||
2. During installation, enter the API key when prompted (stored in Vault)
|
||||
3. In the chat interface, select "tavily" from the MCP Servers dropdown
|
||||
4. The model can now search the web to answer questions
|
||||
|
||||
### Adding Custom MCP Servers
|
||||
|
||||
Edit `librechat-config.gomplate.yaml` to add additional MCP servers:
|
||||
|
||||
```yaml
|
||||
mcpServers:
|
||||
tavily:
|
||||
command: npx
|
||||
args:
|
||||
- "-y"
|
||||
- "tavily-mcp@latest"
|
||||
env:
|
||||
TAVILY_API_KEY: "${TAVILY_API_KEY}"
|
||||
filesystem:
|
||||
command: npx
|
||||
args:
|
||||
- "-y"
|
||||
- "@anthropic/mcp-server-filesystem"
|
||||
- "/app/data"
|
||||
```
|
||||
|
||||
## Adding API Providers
|
||||
|
||||
Edit `librechat-config.gomplate.yaml` to add OpenAI, Anthropic, or other providers:
|
||||
|
||||
```yaml
|
||||
endpoints:
|
||||
openAI:
|
||||
apiKey: "${OPENAI_API_KEY}"
|
||||
models:
|
||||
default:
|
||||
- gpt-4o
|
||||
- gpt-4o-mini
|
||||
fetch: true
|
||||
|
||||
anthropic:
|
||||
apiKey: "${ANTHROPIC_API_KEY}"
|
||||
models:
|
||||
default:
|
||||
- claude-sonnet-4-20250514
|
||||
- claude-3-5-haiku-20241022
|
||||
```
|
||||
|
||||
Store the API keys in Kubernetes secrets and reference them in `values.gomplate.yaml`.
|
||||
|
||||
## Operations
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
just librechat::status
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
just librechat::logs
|
||||
```
|
||||
|
||||
### Restart
|
||||
|
||||
```bash
|
||||
just librechat::restart
|
||||
```
|
||||
|
||||
## Upgrade
|
||||
|
||||
```bash
|
||||
just librechat::upgrade
|
||||
```
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
just librechat::uninstall
|
||||
```
|
||||
|
||||
This removes the Helm release, namespace, and Keycloak client. Vault secrets
|
||||
are preserved.
|
||||
|
||||
To delete Vault secrets:
|
||||
|
||||
```bash
|
||||
just vault::delete librechat/credentials
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
LibreChat deployment includes:
|
||||
|
||||
- **LibreChat**: Main application (Node.js)
|
||||
- **MongoDB**: Conversation and user data storage
|
||||
- **Meilisearch**: Full-text search for conversations
|
||||
|
||||
All components run with Pod Security Standards set to `restricted`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### OIDC Login Fails
|
||||
|
||||
**Symptom**: Redirect loop or error after Keycloak login
|
||||
|
||||
**Check**:
|
||||
|
||||
1. Verify `DOMAIN_CLIENT` and `DOMAIN_SERVER` match your LibreChat URL
|
||||
2. Check Keycloak client redirect URI matches `https://<host>/oauth/openid/callback`
|
||||
|
||||
```bash
|
||||
just keycloak::get-client buunstack librechat
|
||||
```
|
||||
|
||||
### Ollama Models Not Showing
|
||||
|
||||
**Symptom**: No models available in the model selector
|
||||
|
||||
**Check**:
|
||||
|
||||
1. Verify Ollama is running: `just ollama::status`
|
||||
2. Check Ollama has models: `just ollama::list`
|
||||
3. Check LibreChat logs for connection errors: `just librechat::logs`
|
||||
|
||||
### MCP Not Working
|
||||
|
||||
**Symptom**: MCP server not available in dropdown
|
||||
|
||||
**Check**:
|
||||
|
||||
1. Verify Tavily secret exists:
|
||||
|
||||
```bash
|
||||
kubectl get secret tavily-api-key -n librechat
|
||||
```
|
||||
|
||||
2. Check for MCP errors in logs:
|
||||
|
||||
```bash
|
||||
just librechat::logs | grep -i mcp
|
||||
```
|
||||
|
||||
3. Verify `librechat-config` ConfigMap has MCP configuration:
|
||||
|
||||
```bash
|
||||
kubectl get configmap librechat-config -n librechat -o yaml
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [LibreChat Website](https://www.librechat.ai/)
|
||||
- [LibreChat Documentation](https://www.librechat.ai/docs)
|
||||
- [LibreChat GitHub](https://github.com/danny-avila/LibreChat)
|
||||
- [LibreChat Helm Chart](https://github.com/danny-avila/librechat-helm)
|
||||
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
||||
- [Tavily API](https://tavily.com/)
|
||||
Reference in New Issue
Block a user