docs/USAGE.md

# 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