SPACE_CONFIG.md

# 🔧 Hugging Face Spaces Configuration

## YAML Front Matter Configuration

File `README.md` harus dimulai dengan YAML front matter configuration:

```yaml
---
title: FunCaptcha Solver API
emoji: 🧩
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
suggested_hardware: cpu-basic
app_file: app.py
---
```

## 📋 Configuration Options

### **Required Fields**

| Field | Value | Description |
|---|---|---|
| `sdk` | `docker` | **CRITICAL**: Must be "docker" for Docker-based spaces |
| `title` | `FunCaptcha Solver API` | Display name di HF Spaces |

### **Optional Fields**

| Field | Default Value | Description | Options |
|---|---|---|---|
| `emoji` | `🧩` | Icon untuk space | Any emoji |
| `colorFrom` | `blue` | Gradient start color | blue, red, green, yellow, etc. |
| `colorTo` | `purple` | Gradient end color | purple, pink, orange, etc. |
| `pinned` | `false` | Pin space di profile | `true` / `false` |
| `app_file` | `app.py` | Main application file | Any Python file |
| `suggested_hardware` | `cpu-basic` | Hardware suggestion | See below |

### **Hardware Options**

| Hardware | Description | Use Case |
|---|---|---|
| `cpu-basic` | **2 vCPU, 16GB RAM** | ✅ **Recommended untuk FunCaptcha** |
| `cpu-upgrade` | 8 vCPU, 32GB RAM | Heavy ML workloads |
| `t4-small` | GPU T4, 15GB VRAM | GPU-accelerated inference |
| `t4-medium` | GPU T4, 60GB RAM | Large GPU models |

> 💡 **Tip**: `cpu-basic` sudah cukup untuk FunCaptcha solver dengan optimasi yang sudah diterapkan.

## 🚨 Common Configuration Errors

### **Error: "Missing configuration in README"**

**Cause**: README.md tidak dimulai dengan YAML front matter

**Solution**: 
```yaml
# ❌ WRONG - Missing YAML front matter
# FunCaptcha Solver API

# ✅ CORRECT - With YAML front matter  
---
title: FunCaptcha Solver API
emoji: 🧩
sdk: docker
---

# FunCaptcha Solver API
```

### **Error: "Invalid SDK configuration"**

**Cause**: `sdk` field salah atau missing

**Solution**:
```yaml
# ❌ WRONG
sdk: python
# or missing sdk field

# ✅ CORRECT
sdk: docker
```

### **Error: "Space fails to start"**

**Possible causes & solutions**:

1. **Dockerfile issues**
   - Check Dockerfile syntax
   - Verify all dependencies installed
   - Check port 7860 exposed

2. **Missing model files**
   - Upload `best.onnx` dan `data.yaml`
   - Check file paths in app.py

3. **Missing API key**
   - Set `FUNCAPTCHA_API_KEY` di space secrets
   - Verify secret name exactly matches

## 🛠️ Customization Options

### **Custom Title & Branding**

```yaml
---
title: Your Custom FunCaptcha API
emoji: 🤖
colorFrom: green
colorTo: blue
---
```

### **Private Space**

Set space visibility to **Private** during creation (tidak bisa diubah via YAML).

### **Custom App File**

Jika rename `app.py`:

```yaml
---
sdk: docker
app_file: main.py  # Your custom filename
---
```

### **Hardware Upgrade**

Untuk performa lebih tinggi:

```yaml
---
sdk: docker
suggested_hardware: cpu-upgrade  # More powerful CPU
---
```

## 🔍 Validation Checklist

Sebelum deploy, pastikan:

- [ ] README.md dimulai dengan `---`
- [ ] `sdk: docker` field present
- [ ] `title` field specified
- [ ] YAML format valid (no tabs, proper indentation)
- [ ] File ends dengan `---` dan newline
- [ ] No syntax errors dalam YAML

## 🧪 Testing Configuration

```bash
# Test YAML syntax locally
python -c "import yaml; yaml.safe_load(open('README.md').read().split('---')[1])"

# Check for required fields
grep -E "^(sdk|title):" README.md
```

## 📝 Template untuk Custom Spaces

```yaml
---
title: "Your App Name"
emoji: 🚀
colorFrom: blue
colorTo: purple  
sdk: docker
pinned: false
suggested_hardware: cpu-basic
app_file: app.py
license: mit
short_description: "Brief description of your space"
---

# Your App Name

Your app description here...
```

---

**⚠️ CRITICAL**: Tanpa proper YAML front matter, HF Spaces tidak akan recognize space sebagai Docker-based application dan akan fail untuk start!

**✅ Quick Fix**: Copy exact YAML header dari `README.md` yang sudah disediakan dalam deployment package.