update
This commit is contained in:
289
docs/ADMIN_DASHBOARD.md
Normal file
289
docs/ADMIN_DASHBOARD.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Admin Dashboard
|
||||
|
||||
## Overview
|
||||
|
||||
The Admin Dashboard provides a web interface to monitor and manage the Munich News system, including AI status, GPU usage, performance metrics, and clustering statistics.
|
||||
|
||||
## Features
|
||||
|
||||
### 📊 System Statistics
|
||||
- Total articles count
|
||||
- Crawled articles
|
||||
- AI summarized articles
|
||||
- Clustered articles
|
||||
- Neutral summaries generated
|
||||
- Active subscribers
|
||||
|
||||
### 🤖 AI Status (Ollama)
|
||||
- Connection status
|
||||
- Current model
|
||||
- Base URL
|
||||
- Enabled/disabled state
|
||||
- Live response test
|
||||
|
||||
### ⚡ GPU Status
|
||||
- GPU availability detection
|
||||
- GPU usage status (CPU vs GPU mode)
|
||||
- Models loaded count
|
||||
- GPU details (layers, model info)
|
||||
- Performance recommendations
|
||||
|
||||
### 🚀 Performance Test
|
||||
- Real-time performance testing
|
||||
- Response time measurement
|
||||
- Performance rating (Excellent/Good/Fair/Slow)
|
||||
- Recommendations for optimization
|
||||
|
||||
### 📦 Available Models
|
||||
- List of downloaded models
|
||||
- Current model indicator
|
||||
- Model management info
|
||||
|
||||
### ⚙️ Configuration
|
||||
- Ollama configuration details
|
||||
- Environment file status
|
||||
- API key status
|
||||
- Base URL and model settings
|
||||
|
||||
### 🔗 AI Clustering & Aggregation
|
||||
- Clustering statistics
|
||||
- Multi-source story detection
|
||||
- Neutral summary generation metrics
|
||||
- Clustering rate percentage
|
||||
|
||||
## Access
|
||||
|
||||
### Using Docker Compose (Recommended)
|
||||
|
||||
The frontend is automatically started with docker-compose:
|
||||
|
||||
```bash
|
||||
# Start all services including frontend
|
||||
docker-compose up -d
|
||||
|
||||
# Check frontend status
|
||||
docker-compose ps frontend
|
||||
|
||||
# View frontend logs
|
||||
docker-compose logs -f frontend
|
||||
```
|
||||
|
||||
The frontend will be available at: **http://localhost:3000**
|
||||
|
||||
### Access Admin Dashboard
|
||||
|
||||
Open your browser and navigate to:
|
||||
```
|
||||
http://localhost:3000/admin.html
|
||||
```
|
||||
|
||||
### Manual Start (Development)
|
||||
|
||||
If you want to run the frontend outside Docker:
|
||||
|
||||
```bash
|
||||
# Navigate to frontend directory
|
||||
cd frontend
|
||||
|
||||
# Install dependencies (first time only)
|
||||
npm install
|
||||
|
||||
# Start the server
|
||||
npm start
|
||||
|
||||
# Or with nodemon for auto-reload
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Screenshots
|
||||
|
||||
### Dashboard Overview
|
||||
The dashboard displays:
|
||||
- Real-time system statistics
|
||||
- AI/Ollama status with live connection test
|
||||
- GPU detection and usage
|
||||
- Performance metrics
|
||||
- Model management
|
||||
- Configuration details
|
||||
|
||||
### Performance Test
|
||||
Click "Run Test" to:
|
||||
- Test AI response time
|
||||
- Get performance rating
|
||||
- Receive optimization recommendations
|
||||
|
||||
### GPU Status
|
||||
Shows:
|
||||
- ✅ GPU Active - Using GPU acceleration (fast)
|
||||
- ⚠️ CPU Mode - Using CPU only (slower)
|
||||
- Recommendations for enabling GPU
|
||||
|
||||
## API Endpoints Used
|
||||
|
||||
The dashboard connects to these backend APIs:
|
||||
|
||||
- `GET /api/stats` - System statistics
|
||||
- `GET /api/ollama/ping` - Ollama connection test
|
||||
- `GET /api/ollama/gpu-status` - GPU detection
|
||||
- `GET /api/ollama/test` - Performance test
|
||||
- `GET /api/ollama/models` - List models
|
||||
- `GET /api/ollama/config` - Configuration
|
||||
|
||||
## Refresh Data
|
||||
|
||||
Click the **🔄 Refresh All** button to reload all dashboard data.
|
||||
|
||||
## Navigation
|
||||
|
||||
- **← Back to Home** - Return to main newsletter page
|
||||
- **Admin Dashboard** link in footer of main page
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Frontend Won't Start
|
||||
|
||||
```bash
|
||||
# Check if port 3000 is in use
|
||||
lsof -i :3000
|
||||
|
||||
# Install dependencies
|
||||
cd frontend
|
||||
npm install
|
||||
|
||||
# Start server
|
||||
npm start
|
||||
```
|
||||
|
||||
### Can't Connect to Backend
|
||||
|
||||
1. **Check backend is running:**
|
||||
```bash
|
||||
docker-compose ps backend
|
||||
```
|
||||
|
||||
2. **Check backend URL in frontend/server.js:**
|
||||
```javascript
|
||||
const API_URL = process.env.API_URL || 'http://localhost:5001';
|
||||
```
|
||||
|
||||
3. **Test backend directly:**
|
||||
```bash
|
||||
curl http://localhost:5001/api/stats
|
||||
```
|
||||
|
||||
### Dashboard Shows Errors
|
||||
|
||||
1. **Check browser console** (F12) for errors
|
||||
2. **Verify backend APIs are accessible**
|
||||
3. **Check CORS settings** if running on different domains
|
||||
|
||||
## Development
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── public/
|
||||
│ ├── index.html # Main newsletter page
|
||||
│ ├── admin.html # Admin dashboard ⭐
|
||||
│ ├── admin.js # Dashboard JavaScript ⭐
|
||||
│ ├── app.js # Main page JavaScript
|
||||
│ └── styles.css # Shared styles
|
||||
├── server.js # Express server
|
||||
└── package.json # Dependencies
|
||||
```
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. **Add API endpoint** in `backend/routes/`
|
||||
2. **Add function** in `frontend/public/admin.js`
|
||||
3. **Add UI section** in `frontend/public/admin.html`
|
||||
4. **Call function** in `refreshAll()` or on button click
|
||||
|
||||
### Styling
|
||||
|
||||
The dashboard uses inline styles for simplicity. Key classes:
|
||||
- `.card` - Dashboard cards
|
||||
- `.stat-row` - Statistic rows
|
||||
- `.status-indicator` - Status dots (green/red/yellow)
|
||||
- `.performance-badge` - Performance ratings
|
||||
- `.btn` - Buttons
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Option 1: Serve with Backend
|
||||
|
||||
Add frontend to docker-compose:
|
||||
|
||||
```yaml
|
||||
frontend:
|
||||
build: ./frontend
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
- API_URL=http://backend:5001
|
||||
depends_on:
|
||||
- backend
|
||||
```
|
||||
|
||||
### Option 2: Static Hosting
|
||||
|
||||
Build and serve static files:
|
||||
|
||||
```bash
|
||||
# Serve with nginx, Apache, or CDN
|
||||
cp -r frontend/public/* /var/www/html/
|
||||
```
|
||||
|
||||
Update API URLs to point to production backend.
|
||||
|
||||
### Option 3: Reverse Proxy
|
||||
|
||||
Use nginx to serve both:
|
||||
|
||||
```nginx
|
||||
location / {
|
||||
proxy_pass http://frontend:3000;
|
||||
}
|
||||
|
||||
location /api/ {
|
||||
proxy_pass http://backend:5001;
|
||||
}
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
### Production Recommendations
|
||||
|
||||
1. **Add authentication** - Protect admin dashboard
|
||||
2. **Use HTTPS** - Encrypt traffic
|
||||
3. **Rate limiting** - Prevent abuse
|
||||
4. **CORS configuration** - Restrict origins
|
||||
5. **API keys** - Secure backend access
|
||||
|
||||
### Basic Auth Example
|
||||
|
||||
```javascript
|
||||
// In server.js
|
||||
const basicAuth = require('express-basic-auth');
|
||||
|
||||
app.use('/admin.html', basicAuth({
|
||||
users: { 'admin': 'your-secure-password' },
|
||||
challenge: true
|
||||
}));
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [API.md](API.md) - Backend API reference
|
||||
- [CHECK_GPU_STATUS.md](CHECK_GPU_STATUS.md) - GPU status checking
|
||||
- [CHANGING_AI_MODEL.md](CHANGING_AI_MODEL.md) - Model management
|
||||
- [AI_NEWS_AGGREGATION.md](AI_NEWS_AGGREGATION.md) - AI features
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check browser console for errors
|
||||
2. Check backend logs: `docker-compose logs backend`
|
||||
3. Verify API endpoints with curl
|
||||
4. Check [TROUBLESHOOTING.md](../TROUBLESHOOTING.md)
|
||||
Reference in New Issue
Block a user