UnForkRAG Admin Access and Monitoring

This document provides comprehensive information about the admin section and monitoring capabilities of the UnForkRAG server.

Overview

The UnForkRAG server includes a secure admin interface that provides:

Admin Authentication: Secure login system with session management
Access Monitoring: Real-time observability of all API requests
User Management: Admin user creation, deletion, and password management
Security Features: Rate limiting, session timeouts, and access logging

Admin Interface

URL

Admin Dashboard: http://127.0.0.1:8000/admin
Login Page: http://127.0.0.1:8000/admin/login

Default Credentials

Username: admin
Password: admin123

⚠️ IMPORTANT: Change the default password immediately after first login!

Features

1. Admin Authentication

Session-based authentication with secure cookies
Password hashing using PBKDF2 with salt
Session timeout (1 hour default, 24 hours with "Remember Me")
Rate limiting for login attempts (5 attempts, 15-minute lockout)
CSRF protection built into forms

2. Monitoring Dashboard

The admin dashboard provides real-time monitoring of:

API Request Logs: View all incoming requests with timestamps, methods, and durations
Request Details: Inspect request and response payloads
Live Updates: Server-Sent Events (SSE) for real-time monitoring
Request Filtering: Filter by API type (Admin, REST API, System)
Performance Metrics: Response times and request patterns

3. User Management

Create new admin users with custom roles
Change passwords securely
Delete users when needed
View user activity and last login times

4. Security Features

Failed login tracking with automatic lockout
Admin access logging to admin_access.log
Session validation and cleanup
Secure cookie settings (httponly, configurable secure flag)

Configuration

Environment Variables

Variable	Default	Description
`UNFORK_ENABLE_ADMIN`	`1`	Enable/disable admin interface
`UNFORK_OBSERVE_MAX`	`200`	Maximum number of observations to keep in memory

Admin Configuration File

The admin system uses admin_config.json for configuration:

{
  "admin_enabled": true,
  "admin_users": {
    "admin": {
      "password_hash": "...",
      "created_at": "2026-02-04T...",
      "last_login": "2026-02-04T...",
      "is_active": true,
      "roles": ["admin"]
    }
  },
  "security": {
    "session_timeout": 3600,
    "max_login_attempts": 5,
    "lockout_duration": 900,
    "require_https": false
  },
  "monitoring": {
    "log_admin_access": true,
    "log_failed_logins": true,
    "max_log_entries": 1000
  }
}

Usage

Starting the Server

python run_server.py --port 8000

The server will display admin credentials on startup:

🚀 Starting on http://127.0.0.1:8000
Admin Credentials:
  Username: admin
  Password: admin123
  Change password after first login!

First-Time Setup

Start the server using the command above
Navigate to http://127.0.0.1:8000/admin
You will be redirected to the login page
Login with the default credentials
Change your password immediately using the "Change Password" link

Changing Password

Navigate to http://127.0.0.1:8000/admin/change-password
Enter your current password
Enter and confirm your new password
Password changes are logged for security

Managing Users

Use the admin_config.py command-line interface:

# Create a new admin user
python admin_config.py create-user john mysecurepassword

# List all admin users
python admin_config.py list-users

# Delete a user
python admin_config.py delete-user john

# Change password
python admin_config.py change-password admin admin123 newpassword

# View configuration
python admin_config.py show-config

Monitoring Features

Real-Time Observability

The admin dashboard shows:

Request Timeline: Chronological list of all API requests
Request Details: Method, path, duration, and payload
Status Indicators: Color-coded badges for different request types
Live Updates: Automatic updates via Server-Sent Events

Request Types

Admin: Requests to admin endpoints (/admin/*)
API: REST API requests (/api/*)
System: Other system requests (Chroma, Qdrant, Ollama)

Performance Monitoring

Response Times: Track API performance
Request Patterns: Identify usage trends
Error Tracking: Monitor failed requests
Session Activity: Track admin user sessions

Security Best Practices

1. Change Default Password

python admin_config.py change-password admin admin123 your-new-password

2. Create Additional Admin Users

python admin_config.py create-user yourname yoursecurepassword

3. Monitor Access Logs

Check admin_access.log regularly for suspicious activity:

tail -f admin_access.log

4. Enable HTTPS in Production

Set require_https: true in the security configuration for production deployments.

5. Regular Password Rotation

Encourage regular password changes for all admin users.

Troubleshooting

Admin Interface Not Accessible

Check environment variable:
```
echo $UNFORK_ENABLE_ADMIN
```
Should return 1
Check admin_config.json exists and is valid
Restart the server after making configuration changes

Login Issues

Check admin_config.json for user existence
Verify password (case-sensitive)
Check rate limiting - wait 15 minutes if locked out
Clear browser cookies if session issues persist

Monitoring Not Working

Check UNFORK_OBSERVE_MAX environment variable
Verify admin authentication is working
Check browser console for JavaScript errors

API Endpoints

Admin Endpoints

Endpoint	Method	Description
`/admin`	GET	Admin dashboard (requires authentication)
`/admin/login`	GET/POST	Login page and authentication
`/admin/logout`	GET	Logout and session cleanup
`/admin/change-password`	GET/POST	Password change interface

Monitoring Endpoints

Endpoint	Method	Description
`/api/observe`	GET	List recent observations
`/api/observe/<id>`	GET	Get specific observation
`/api/observe/stream`	GET	Server-Sent Events stream

File Structure

unforkrag/
├── admin_config.py          # Admin configuration and user management
├── admin_auth.py           # Authentication middleware
├── admin_config.json       # Admin configuration file (auto-created)
├── admin_access.log        # Admin access logs (auto-created)
├── unfork_server.py        # Main server with admin integration
├── run_server.py          # Server launcher
└── ADMIN_README.md        # This documentation file

Support

For issues related to admin access and monitoring:

Check the server logs for error messages
Verify configuration files are valid JSON
Ensure all required modules are installed
Check browser developer tools for client-side errors

Security Notes

Passwords are hashed using PBKDF2 with salt
Sessions use secure, random tokens
Failed login attempts are rate-limited
Admin access is logged for audit purposes
Cookies are marked as HttpOnly for security
Consider enabling HTTPS in production environments

FilesExpand file tree

ADMIN_README.md

Latest commit

History