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

# Minimal configuration for testing
SERVICE_PORT=7860
MODEL_NAME=distilbert-base-uncased
DEBUG_MODE=true
FILEBROWSER_ENABLED=true
WEBDAV_ENABLED=true

Production Gradio Service

# 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

# 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

# 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