docs/DEPLOYMENT_HF_SPACES.md

# 🚀 Déploiement sur Hugging Face Spaces avec Docker

Guide complet pour déployer le jeu RTS sur Hugging Face Spaces en utilisant le framework Docker.

---

## 📋 Prérequis

1. **Compte Hugging Face** : https://huggingface.co/join
2. **Git installé** localement
3. **Git LFS installé** (pour les gros fichiers)
   ```bash
   git lfs install
   ```

---

## 🎯 Configuration Actuelle

Le projet est **déjà configuré** pour HF Spaces ! ✅

### Fichiers de Configuration

**1. README.md (Metadata YAML)**
```yaml
---
title: RTS Commander
emoji: 🎮
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---
```

**2. Dockerfile**
- Port: 7860 (requis par HF Spaces)
- Base: Python 3.11-slim
- Server: Uvicorn + FastAPI
- WebSocket support: ✅

**3. Structure**
```
web/
├── Dockerfile          ✅ Prêt pour HF Spaces
├── README.md           ✅ Avec metadata YAML
├── requirements.txt    ✅ Dépendances Python
├── app.py             ✅ FastAPI + WebSocket
└── static/            ✅ Assets (HTML, JS, CSS, sons)
```

---

## 🚀 Déploiement - Méthode 1: Via l'Interface Web (Recommandé)

### Étape 1: Créer un Space

1. Aller sur https://huggingface.co/spaces
2. Cliquer **"Create new Space"**
3. Remplir le formulaire :
   - **Space name**: `rts-commander` (ou votre choix)
   - **License**: MIT
   - **Select the Space SDK**: **Docker** ⚠️ IMPORTANT !
   - **Space hardware**: CPU basic (gratuit) ou GPU (payant)
   - **Visibility**: Public ou Private

4. Cliquer **"Create Space"**

---

### Étape 2: Préparer le Répertoire Local

```bash
cd /home/luigi/rts/web

# Vérifier que tous les fichiers essentiels sont présents
ls -la
# Doit contenir: Dockerfile, README.md, app.py, requirements.txt, static/, backend/
```

---

### Étape 3: Initialiser Git et Pousser

```bash
# Si ce n'est pas déjà un repo git
git init

# Ajouter le remote HF Space (remplacer USERNAME et SPACENAME)
git remote add space https://huggingface.co/spaces/USERNAME/SPACENAME

# Ajouter tous les fichiers
git add .

# Commit
git commit -m "Initial commit: RTS Commander v2.0"

# Pousser vers HF Space
git push --set-upstream space main
```

**Note**: Si vous avez déjà un remote `origin`, utilisez un nom différent comme `space`.

---

### Étape 4: Attendre le Build

1. Aller sur votre Space : `https://huggingface.co/spaces/USERNAME/SPACENAME`
2. HF va automatiquement :
   - ✅ Détecter le Dockerfile
   - ✅ Builder l'image Docker
   - ✅ Lancer le container sur le port 7860
   - ✅ Exposer l'application publiquement

**Temps de build**: 2-5 minutes ⏱️

---

### Étape 5: Tester l'Application

Une fois le build terminé :
1. Ouvrir l'URL : `https://USERNAME-SPACENAME.hf.space`
2. Le jeu devrait se charger ! 🎮

**Tests rapides** :
- ✅ UI se charge
- ✅ WebSocket connecté (vérifier console)
- ✅ Créer des unités
- ✅ Sons fonctionnent
- ✅ Control groups 1-9
- ✅ Multi-langue (EN/FR/繁中)

---

## 🚀 Déploiement - Méthode 2: Via CLI avec `huggingface_hub`

### Installation

```bash
pip install huggingface_hub

# Login (nécessite un token)
huggingface-cli login
```

### Créer le Space

```bash
# Créer un nouveau Space
huggingface-cli repo create rts-commander --type space --space_sdk docker

# Cloner le Space
git clone https://huggingface.co/spaces/USERNAME/rts-commander
cd rts-commander

# Copier les fichiers du projet
cp -r /home/luigi/rts/web/* .

# Git add, commit, push
git add .
git commit -m "Initial commit: RTS Commander v2.0"
git push
```

---

## 🚀 Déploiement - Méthode 3: Upload Direct (Simple)

### Via l'Interface Web

1. Aller sur votre Space
2. Cliquer **"Files"** → **"Add file"** → **"Upload files"**
3. Glisser-déposer TOUS les fichiers du répertoire `web/` :
   - `Dockerfile`
   - `README.md` (avec metadata YAML)
   - `app.py`
   - `requirements.txt`
   - `localization.py`
   - `ai_analysis.py`
   - `start.py`
   - Dossier `backend/`
   - Dossier `static/`
   - etc.

4. Cliquer **"Commit changes to main"**
5. HF va automatiquement rebuild !

---

## ⚙️ Configuration Avancée

### Variables d'Environnement

Si vous avez besoin de variables d'environnement :

1. Aller dans **Settings** du Space
2. Section **"Repository secrets"**
3. Ajouter des variables (ex: `API_KEY`, `DEBUG`, etc.)
4. Accessible via `os.environ['VAR_NAME']` dans le code

### Logs et Debugging

Pour voir les logs du container :
1. Aller dans votre Space
2. Section **"Logs"** (en bas)
3. Voir les logs en temps réel (stdout/stderr)

**Commandes utiles dans les logs** :
```
INFO:     Uvicorn running on http://0.0.0.0:7860
INFO:     WebSocket connection accepted
ERROR:    [Erreurs éventuelles]
```

---

## 🐳 Dockerfile Optimisé pour HF Spaces

Le Dockerfile actuel est déjà optimisé, mais voici les détails :

```dockerfile
# Python 3.11 slim (plus léger que full)
FROM python:3.11-slim

# Répertoire de travail
WORKDIR /app

# Dépendances système (gcc pour compilation de packages Python)
RUN apt-get update && apt-get install -y \
    gcc g++ make \
    && rm -rf /var/lib/apt/lists/*

# Installation des dépendances Python
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copie du code
COPY . .

# Port 7860 (REQUIS par HF Spaces)
EXPOSE 7860

# Variables d'environnement
ENV GRADIO_SERVER_NAME="0.0.0.0"
ENV GRADIO_SERVER_PORT=7860

# Lancement avec Uvicorn
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
```

**Points importants** :
- ⚠️ **Port 7860** : OBLIGATOIRE pour HF Spaces
- ✅ **Host 0.0.0.0** : Pour accepter les connexions externes
- ✅ **Uvicorn** : Server ASGI pour FastAPI
- ✅ **WebSocket** : Supporté par Uvicorn

---

## 📦 Fichiers à Inclure

### Essentiels (OBLIGATOIRES)

```
web/
├── Dockerfile                    ⚠️ OBLIGATOIRE
├── README.md                     ⚠️ Avec metadata YAML
├── requirements.txt              ⚠️ Dépendances
├── app.py                        ⚠️ Point d'entrée
├── localization.py
├── ai_analysis.py
├── start.py
└── ...
```

### Assets et Code

```
web/
├── backend/                      📁 Logic backend
│   └── app/
├── static/                       📁 Frontend
│   ├── game.js
│   ├── hints.js
│   ├── sounds.js
│   ├── index.html
│   ├── styles.css
│   └── sounds/                   🔊 Audio files
│       ├── fire.wav
│       ├── explosion.wav
│       ├── build.wav
│       └── ready.wav
└── ...
```

### Optionnels

```
web/
├── docs/                         📚 Documentation (optionnel)
├── tests/                        🧪 Tests (optionnel)
├── docker-compose.yml            (non utilisé par HF)
└── .dockerignore                 (recommandé)
```

---

## 🔧 Résolution de Problèmes

### Problème 1: Build Failed

**Erreur**: `Error building Docker image`

**Solutions** :
1. Vérifier que `Dockerfile` est à la racine
2. Vérifier `requirements.txt` (pas de packages cassés)
3. Voir les logs de build dans l'interface HF
4. Tester le build localement :
   ```bash
   cd /home/luigi/rts/web
   docker build -t rts-test .
   docker run -p 7860:7860 rts-test
   ```

---

### Problème 2: Container Crashes

**Erreur**: Container démarre puis crash immédiatement

**Solutions** :
1. Vérifier les logs dans l'interface HF
2. Vérifier que le port 7860 est bien exposé
3. Vérifier que `app:app` existe dans `app.py`
4. Tester localement :
   ```bash
   cd /home/luigi/rts/web
   python -m uvicorn app:app --host 0.0.0.0 --port 7860
   ```

---

### Problème 3: WebSocket ne se connecte pas

**Erreur**: `WebSocket connection failed`

**Solutions** :
1. Vérifier l'URL WebSocket dans `game.js`
2. Pour HF Spaces, utiliser l'URL relative :
   ```javascript
   const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
   const wsUrl = `${protocol}//${window.location.host}/ws`;
   ```
3. Vérifier que Uvicorn supporte WebSocket (déjà ok)

---

### Problème 4: Assets ne se chargent pas

**Erreur**: `404 Not Found` pour JS/CSS/sons

**Solutions** :
1. Vérifier les chemins dans `index.html` :
   ```html
   <script src="/static/game.js"></script>
   <link rel="stylesheet" href="/static/styles.css">
   ```
2. Vérifier que `static/` est bien copié dans le Dockerfile
3. Vérifier la configuration StaticFiles dans `app.py` :
   ```python
   app.mount("/static", StaticFiles(directory="static"), name="static")
   ```

---

## 🎮 Configuration Spécifique au Jeu

### WebSocket URL Dynamique

Pour que le jeu fonctionne sur HF Spaces, vérifier dans `game.js` :

```javascript
// ✅ BON : URL dynamique
const wsUrl = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/ws`;

// ❌ MAUVAIS : URL hardcodée
const wsUrl = 'ws://localhost:8000/ws';
```

### Taille des Assets

HF Spaces gratuit a des limites :
- **Espace disque** : ~50 GB
- **RAM** : 16 GB (CPU basic)
- **CPU** : 2 cores

Votre projet est léger :
- Code : ~5 MB
- Sons : 78 KB
- **Total** : ~5 MB ✅ Parfait !

---

## 📊 Performance sur HF Spaces

### CPU Basic (Gratuit)

**Specs** :
- 2 vCPU
- 16 GB RAM
- Permanent (ne s'éteint pas)

**Performance attendue** :
- ✅ Chargement : <2 secondes
- ✅ WebSocket : <100ms latency
- ✅ Gameplay : 60 FPS
- ✅ Sons : Fluides
- ✅ Multi-joueurs : 10-20 simultanés

**Conclusion** : CPU basic est **largement suffisant** ! 🎉

---

## 🔒 Sécurité et Limites

### Rate Limiting

HF Spaces peut limiter les requêtes :
- **Recommandation** : Ajouter rate limiting dans `app.py`

```python
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

@app.get("/")
@limiter.limit("100/minute")
async def root(request: Request):
    # ...
```

### WebSocket Limits

- **Max connections** : ~100-200 (CPU basic)
- **Timeout** : 30 minutes d'inactivité
- **Reconnexion** : À implémenter côté client

---

## 🌐 Domaine Personnalisé (Optionnel)

Pour utiliser votre propre domaine :

1. Passer à **HF Spaces PRO** ($9/mois)
2. Configurer un CNAME DNS :
   ```
   rts.votredomaine.com CNAME USERNAME-SPACENAME.hf.space
   ```
3. Ajouter le domaine dans Settings du Space

---

## 📈 Monitoring

### Logs en Temps Réel

```bash
# Via CLI (si huggingface_hub installé)
huggingface-cli space logs USERNAME/SPACENAME --follow
```

### Metrics

HF Spaces fournit :
- **CPU usage**
- **RAM usage**
- **Network I/O**
- **Requests per minute**

Accessible dans **Settings** → **Analytics**

---

## 🚀 Déploiement Express (TL;DR)

**3 commandes pour déployer** :

```bash
# 1. Aller dans le répertoire
cd /home/luigi/rts/web

# 2. Créer un Space sur HF avec SDK=Docker
# Via web: https://huggingface.co/new-space

# 3. Push
git remote add space https://huggingface.co/spaces/USERNAME/SPACENAME
git push space main
```

**C'est tout ! 🎉**

---

## 📚 Ressources Utiles

- **HF Spaces Docs** : https://huggingface.co/docs/hub/spaces
- **Docker SDK** : https://huggingface.co/docs/hub/spaces-sdks-docker
- **FastAPI Docs** : https://fastapi.tiangolo.com/
- **WebSocket** : https://fastapi.tiangolo.com/advanced/websockets/

---

## ✅ Checklist Finale

Avant de déployer, vérifier :

- [ ] `Dockerfile` présent et port = 7860
- [ ] `README.md` avec metadata YAML (`sdk: docker`)
- [ ] `requirements.txt` à jour
- [ ] `app.py` avec `app = FastAPI()`
- [ ] WebSocket URL dynamique dans `game.js`
- [ ] Tous les assets dans `static/`
- [ ] Build Docker local réussi
- [ ] Compte HF créé
- [ ] Space créé avec SDK=Docker

---

## 🎊 Résultat Attendu

Après déploiement réussi :

**URL** : `https://USERNAME-SPACENAME.hf.space`

**Features** :
- ✅ Jeu RTS complet
- ✅ WebSocket temps réel
- ✅ Sons + Control groups
- ✅ Multi-langue (EN/FR/繁中)
- ✅ Superweapon nuke
- ✅ Responsive UI
- ✅ 60 FPS gameplay

**Accessible** :
- 🌐 Publiquement
- 📱 Sur mobile/desktop
- 🚀 Sans installation
- 🎮 Prêt à jouer !

---

**Temps total de déploiement** : 5-10 minutes ⚡

**Félicitations ! Votre jeu RTS est maintenant en ligne ! 🎉**