75 lines
2.3 KiB
Markdown
75 lines
2.3 KiB
Markdown
# Hermes Service - Nginx Deployment with Security Features
|
|
|
|
## Overview
|
|
|
|
This service provides a multi-user Hermes Agent API that can be deployed behind Nginx with IP address filtering and API key authentication capabilities.
|
|
|
|
## Configuration
|
|
|
|
The service uses a `config.yaml` file for configuration. Key security features include:
|
|
|
|
### IP Address Checking
|
|
- Enable with `security.enable_ip_check: true`
|
|
- Configure allowed IPs in `security.allowed_ips` (supports CIDR notation)
|
|
- Works with X-Forwarded-For header when behind Nginx
|
|
|
|
### API Key Authentication
|
|
- Enable with `security.enable_api_key: true`
|
|
- Choose authentication method: `header` (custom header) or `bearer` (Authorization header)
|
|
- For `bearer` method, use `Authorization: Bearer <apikey>` header
|
|
- For `header` method, configure custom header name via `security.api_key_header`
|
|
- Define valid API keys in `security.api_keys`
|
|
|
|
### Nginx Integration
|
|
- Real IP detection from X-Forwarded-For header
|
|
- Trusted proxy configuration
|
|
- Service binds to localhost by default for security
|
|
|
|
## Deployment with Nginx
|
|
|
|
1. **Configure the service** (`config.yaml`):
|
|
```yaml
|
|
security:
|
|
enable_ip_check: true
|
|
allowed_ips:
|
|
- "192.168.1.0/24"
|
|
- "203.0.113.0/24"
|
|
enable_api_key: true
|
|
api_keys:
|
|
- key: "your-secret-api-key"
|
|
description: "Production API key"
|
|
```
|
|
|
|
2. **Start the Hermes service**:
|
|
```bash
|
|
python main.py
|
|
# Service will listen on 127.0.0.1:9120
|
|
```
|
|
|
|
3. **Configure Nginx** (see `nginx.conf.example`):
|
|
- Set up reverse proxy to localhost:9120
|
|
- Configure SSL (recommended)
|
|
- Optional: Add additional IP restrictions at Nginx level
|
|
|
|
4. **Test the deployment**:
|
|
```bash
|
|
# Health check (no auth required)
|
|
curl http://your-domain.com/health
|
|
|
|
# API call with API key
|
|
curl -H "X-API-Key: your-secret-api-key" \
|
|
-X POST http://your-domain.com/api/v1/sessions \
|
|
-d '{"user_id": "test"}'
|
|
```
|
|
|
|
## Security Best Practices
|
|
|
|
- Always run behind Nginx or similar reverse proxy in production
|
|
- Use HTTPS/SSL for all communications
|
|
- Regularly rotate API keys
|
|
- Restrict allowed IPs to known client networks
|
|
- Monitor access logs for suspicious activity
|
|
|
|
## Configuration Reference
|
|
|
|
See `config.yaml` for complete configuration options and examples. |