File size: 4,942 Bytes
9b205e1 a9b851c 9b205e1 cf5db51 9b205e1 cf5db51 9b205e1 a9b851c 9b205e1 a9b851c 9b205e1 a9b851c 9b205e1 a9b851c 9b205e1 519d346 9b205e1 a9b851c 9b205e1 a9b851c 9b205e1 a9b851c 9b205e1 a9b851c 9b205e1 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | # Usage Guide
Quick reference for configuring and using the Universal HF Docker Template.
## Environment Variables
### Core Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `SERVICE_PORT` | `7860` | Port for your core service |
| `MODEL_NAME` | - | Hugging Face model name to load |
| `SERVICE_TITLE` | `My HF Model Service` | Title for your service interface |
| `HF_TOKEN` | - | Hugging Face API token |
| `DEBUG_MODE` | `false` | Enable debug logging |
### Optional Services
| Variable | Default | Description |
|----------|---------|-------------|
| `FILEBROWSER_ENABLED` | `false` | Enable web-based file management |
| `WEBDAV_ENABLED` | `false` | Enable WebDAV file synchronization service |
| `PERSISTENCE_ENABLED` | `false` | Enable automatic backup/restore |
| `RESTIC_ENABLED` | `false` | Enable restic backup service |
| `CLOUDFLARED_ENABLED` | `false` | Enable Cloudflare tunnel |
| `FRPC_ENABLED` | `false` | Enable frpc reverse proxy |
⚠️ **Important**: `PERSISTENCE_ENABLED` and `RESTIC_ENABLED` cannot both be `true` at the same time, you can only choose one backup service.
### Service-Specific Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `DATASET_ID` | - | Dataset ID for backups (`username/dataset-name`) |
| `SYNC_INTERVAL` | `7200` | Backup interval in seconds |
| `WEBDAV_HOST` | `0.0.0.0` | WebDAV server host address |
| `WEBDAV_PORT` | `8081` | WebDAV server port |
| `WEBDAV_USERNAME` | `webdav` | WebDAV authentication username |
| `WEBDAV_PASSWORD` | `webdav123` | WebDAV authentication password |
| `WEBDAV_ROOT_DIR` | `/home/user/webdav` | WebDAV root directory |
| `WEBDAV_ENABLE_UI` | `true` | Enable WebDAV web interface |
| `CLOUDFLARED_TUNNEL_TOKEN` | - | Cloudflare tunnel token |
| `FRPC_SERVER_ADDR` | - | frp server address |
| `FRPC_AUTH_TOKEN` | - | frp authentication token |
## Configuration Examples
### Basic Development Setup
```bash
# Minimal configuration for testing
SERVICE_PORT=7860
MODEL_NAME=distilbert-base-uncased
DEBUG_MODE=true
FILEBROWSER_ENABLED=true
WEBDAV_ENABLED=true
```
### Production Gradio Service
```bash
# Core service
SERVICE_PORT=7860
MODEL_NAME=microsoft/DialoGPT-medium
SERVICE_TITLE="My Chat Bot"
HF_TOKEN=your_hf_token
# Infrastructure
FILEBROWSER_ENABLED=true
WEBDAV_ENABLED=true
WEBDAV_PASSWORD=secure_password_123
PERSISTENCE_ENABLED=true
DATASET_ID=username/dataset
CLOUDFLARED_ENABLED=true
CLOUDFLARED_TUNNEL_TOKEN=your_tunnel_token
```
### Custom Service with Persistence
```bash
# Your custom service configuration
SERVICE_PORT=7860
HF_TOKEN=your_token
# Data persistence
PERSISTENCE_ENABLED=true
DATASET_ID=username/dataset
SYNC_INTERVAL=3600
# File management
FILEBROWSER_ENABLED=true
```
## Port Configuration
The template uses these ports by default:
| Port | Service | Description |
|------|---------|-------------|
| `7860` | Core Service | HuggingFace Spaces standard port |
| `8080` | File Browser | Web-based file management |
| `8081` | WebDAV | File synchronization protocol |
| `9000` | Minio API | S3-compatible object storage |
| `9001` | Minio Console | Web management interface |
Configure `SERVICE_PORT` to change the core service port if needed. Individual services can be configured with their respective environment variables.
## Troubleshooting
| Problem | Solution |
|---------|----------|
| Service won't start | Check `scripts/start/core-service-start.sh` exists and is executable |
| Permission denied | Verify file ownership: `chown user:user /home/user/script/start/*` |
| Service not starting | Check `*_ENABLED=true` and required environment variables |
| Cloudflared fails | Verify `CLOUDFLARED_TUNNEL_TOKEN` is valid |
| File Browser inaccessible | Ensure `FILEBROWSER_ENABLED=true` and port is available |
| WebDAV not working | Check `WEBDAV_ENABLED=true` and verify credentials |
| WebDAV access denied | Verify `WEBDAV_USERNAME` and `WEBDAV_PASSWORD` are correct |
| Backup fails | Verify `HF_TOKEN` has write access to `DATASET_ID` |
| Variables not set | Check Hugging Face Spaces settings |
| Boolean values | Use lowercase `true`/`false` |
### Debugging Commands
```bash
# Check running processes
ps aux | grep -E "(python|cloudflared|frpc|filebrowser|flydav)"
# Check environment variables
env | grep -E "(SERVICE_|MODEL_|ENABLED|TOKEN|WEBDAV_)"
# Check service logs
tail -f /tmp/*.log
# Test network connectivity
curl -I http://localhost:7860 # Core service
curl -I http://localhost:8080 # File Browser
curl -I http://localhost:8081 # WebDAV
# Test WebDAV connectivity (with authentication)
curl -I -u username:password http://localhost:8081/webdav
```
## Best Practices
- Use Hugging Face Spaces secrets for sensitive tokens
- Test configuration locally before deploying
- Monitor resource usage and adjust `SYNC_INTERVAL` accordingly
- Document custom environment variables for your service
|