Oliver/librechat-analytics
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Rewrite README with full install guide, nginx setup, and troubleshooting

Browse source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
DJP 2026-03-11 19:12:38 -04:00
parent dea8207620
commit ebf81ae48f
1 changed files with 78 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

127
README.md
View file

@ -10,36 +10,47 @@ Usage analytics dashboard for LibreChat. Queries the existing MongoDB to show mo
- **Agents** — Agent usage with underlying model resolution
- **Time Filtering** — 24H, 7D, 30D, or custom date range
- **Auto-refresh** — Updates every 60 seconds
- **API Key Auth** — Dashboard protected by API key
- **API Key Auth** — Dashboard protected by API key (prompted on first visit)
## Prerequisites
- Docker and Docker Compose
- Access to LibreChat's MongoDB (same Docker network)
- LibreChat already running with MongoDB
- Access to LibreChat's nginx config (for proxy setup)
## Quick Start
## Installation
### 1. Clone the repo
```bash
git clone git@bitbucket.org:zlalani/librechat-analytics.git
cd /opt
git clone https://x-token-auth:{ACCESS_TOKEN}@bitbucket.org/zlalani/librechat-analytics.git
cd librechat-analytics
```
Or with SSH:
```bash
git clone git@bitbucket.org:zlalani/librechat-analytics.git
```
### 2. Configure environment
```bash
cp .env.example .env
nano .env
```
Edit `.env`:
Set the following values:
```
MONGO_URI=mongodb://mongodb:27017/LibreChat
DASHBOARD_API_KEY=your-secure-key-here
PORT=3001
```
**Important:** Change `DASHBOARD_API_KEY` to a secure value. This key is required to access the dashboard.
**Important:**
- Change `DASHBOARD_API_KEY` to a secure value. This is required to access the dashboard.
- Do NOT use `&` or other special characters in the API key (breaks URL parsing).
- `mongodb` in the URI is the container name of LibreChat's MongoDB — change if yours is different.
### 3. Build and run
@ -47,15 +58,31 @@ PORT=3001
docker compose up -d --build
```
### 4. Connect to LibreChat's Docker network
The container automatically joins LibreChat's Docker network (`librechat_default`) so it can reach MongoDB. If your LibreChat network has a different name, edit `docker-compose.yml` and change the `name:` under the `librechat` network.
The analytics container needs to reach LibreChat's MongoDB. Connect it to the same network:
### 4. Configure Nginx
```bash
docker network connect librechat_default librechat-analytics
Edit LibreChat's nginx config to proxy the dashboard. The nginx config location depends on your setup:
- **Standard deploy:** `/home/<user>/LibreChat/client/nginx.conf`
- **Alternate location:** `/opt/LibreChat/client/nginx.conf`
Add this location block **before** the `location /api` block:
```nginx
location /librechat-analytics/ {
proxy_pass http://librechat-analytics:3001/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
```
> **Note:** If your LibreChat network has a different name, check with `docker network ls`.
Then reload nginx:
```bash
docker exec LibreChat-NGINX nginx -s reload
```
### 5. Verify
@ -64,47 +91,16 @@ docker network connect librechat_default librechat-analytics
curl http://localhost:3001/health
# Test API (requires API key)
curl -H "x-api-key: your-secure-key-here" http://localhost:3001/api/summary?period=30d
curl -H "x-api-key: your-secure-key-here" 'http://localhost:3001/api/summary?period=30d'
```
### 6. Access the dashboard
Open `http://localhost:3001` in your browser. You'll be prompted to enter the API key on first visit.
Open `https://your-domain/librechat-analytics/` in your browser.
## Nginx Proxy (Optional)
On first visit you'll be prompted to enter the API key. It gets saved in your browser's localStorage so you only need to enter it once.
To expose via LibreChat's existing nginx, add to the nginx config (before `location /api`):
```nginx
location /analytics/ {
proxy_pass http://librechat-analytics:3001/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
```
Then restart nginx:
```bash
docker exec <nginx-container> nginx -s reload
```
Dashboard will be available at `https://your-domain/analytics/`.
## Server Deployment
### On the server:
```bash
cd /opt
git clone git@bitbucket.org:zlalani/librechat-analytics.git
cd librechat-analytics
cp .env.example .env
# Edit .env with your MONGO_URI and DASHBOARD_API_KEY
docker compose up -d --build
docker network connect librechat_default librechat-analytics
```
### Updating:
## Updating
```bash
cd /opt/librechat-analytics
@ -112,17 +108,31 @@ git pull
docker compose up -d --build
```
No need to reconfigure nginx or re-enter the API key after updates.
## Ports
| Service | Port | Notes |
|---------|------|-------|
| Analytics Dashboard | 3001 | Bound to 127.0.0.1 only |
| Analytics Dashboard | 3001 | Bound to 127.0.0.1 only (not exposed externally) |
| LibreChat | 3080 | No conflict |
| Code Interpreter | 8000/8005 | No conflict |
Does not clash with LibreChat (3080) or Code Interpreter (8000/8005).
The dashboard is only accessible externally through the nginx proxy.
## Authentication
The dashboard is protected by an API key set in `.env`. When accessing the dashboard:
1. Browser prompts for the API key on first visit
2. Key is stored in browser localStorage
3. All API requests include the key in the `x-api-key` header
To reset the key in your browser: open DevTools (F12) > Application > Local Storage > delete `analyticsApiKey`, then refresh.
## Cost Calculation
Costs come directly from LibreChat's `transactions` collection. LibreChat stores `tokenValue = rawAmount × rate` where rate is USD per 1M tokens. The dashboard reads these pre-calculated values — it does not independently calculate pricing.
Costs come directly from LibreChat's `transactions` collection. LibreChat stores `tokenValue = rawAmount x rate` where rate is USD per 1M tokens. The dashboard reads these pre-calculated values — it does not independently calculate pricing.
## API Endpoints
@ -137,3 +147,22 @@ All require `x-api-key` header. All accept `?period=24h|7d|30d|custom&start=ISO&
| `GET /api/top-agents?limit=10` | Agents ranked by cost |
| `GET /api/cost-breakdown` | Per-model input vs output cost split |
| `GET /api/usage-over-time` | Time-series tokens and cost |
## Troubleshooting
**No data showing:**
- Check the time period — try 30D if there's no recent usage
- Check container logs: `docker logs librechat-analytics --tail 20`
- Verify MongoDB connection: the health endpoint should return `{"status":"ok"}`
**API key not prompting:**
- Clear localStorage: DevTools > Application > Local Storage > delete `analyticsApiKey`
- Hard refresh: Ctrl+Shift+R
**Container can't reach MongoDB:**
- Verify network: `docker network inspect librechat_default` — both `mongodb` and `librechat-analytics` should be listed
- If LibreChat uses a different network name, update `docker-compose.yml`
**Nginx 502 Bad Gateway:**
- Check the analytics container is running: `docker ps | grep analytics`
- Check it's on the right network: `docker network inspect librechat_default`