Spaces:

Luigi
/

rts-commander

Sleeping

App Files Files Community

rts-commander / docs /DEPLOYMENT_HF_SPACES.md

Luigi

deploy(web): full clean snapshot with app code and assets

12d64f8 about 2 months ago

preview code

raw

history blame contribute delete

12.5 kB

🚀 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

Compte Hugging Face : https://huggingface.co/join
Git installé localement
Git LFS installé (pour les gros fichiers)
```
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

# 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

Aller sur votre Space : https://huggingface.co/spaces/USERNAME/SPACENAME
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é :

Ouvrir l'URL : https://USERNAME-SPACENAME.hf.space
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

pip install huggingface_hub

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

Créer le Space

# 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

Aller sur votre Space
Cliquer "Files" → "Add file" → "Upload files"
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.
Cliquer "Commit changes to main"
HF va automatiquement rebuild !

⚙️ Configuration Avancée

Variables d'Environnement

Si vous avez besoin de variables d'environnement :

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

Logs et Debugging

Pour voir les logs du container :

Aller dans votre Space
Section "Logs" (en bas)
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 :

# 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 :

Vérifier que Dockerfile est à la racine
Vérifier requirements.txt (pas de packages cassés)
Voir les logs de build dans l'interface HF

Tester le build localement :

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 :

Vérifier les logs dans l'interface HF
Vérifier que le port 7860 est bien exposé
Vérifier que app:app existe dans app.py

Tester localement :

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 :

Vérifier l'URL WebSocket dans game.js

Pour HF Spaces, utiliser l'URL relative :

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

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 :

Vérifier les chemins dans index.html :

<script src="/static/game.js"></script>
<link rel="stylesheet" href="/static/styles.css">

Vérifier que static/ est bien copié dans le Dockerfile

Vérifier la configuration StaticFiles dans app.py :

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 :

// ✅ 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

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 :

Passer à HF Spaces PRO ($9/mois)

Configurer un CNAME DNS :

rts.votredomaine.com CNAME USERNAME-SPACENAME.hf.space

Ajouter le domaine dans Settings du Space

📈 Monitoring

Logs en Temps Réel

# 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 :

# 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 ! 🎉

🚀 Déploiement sur Hugging Face Spaces avec Docker

📋 Prérequis

🎯 Configuration Actuelle

Fichiers de Configuration

1. README.md (Metadata YAML) ```yaml

title: RTS Commander emoji: 🎮 colorFrom: blue colorTo: green sdk: docker pinned: false license: mit

Étape 3: Initialiser Git et Pousser

Étape 4: Attendre le Build

Étape 5: Tester l'Application

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

Installation

Créer le Space

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

Via l'Interface Web

⚙️ Configuration Avancée

Variables d'Environnement

Logs et Debugging

🐳 Dockerfile Optimisé pour HF Spaces

📦 Fichiers à Inclure

Essentiels (OBLIGATOIRES)

Assets et Code

Optionnels

🔧 Résolution de Problèmes

Problème 1: Build Failed

Problème 2: Container Crashes

Problème 3: WebSocket ne se connecte pas

Problème 4: Assets ne se chargent pas

🎮 Configuration Spécifique au Jeu

WebSocket URL Dynamique

Taille des Assets

📊 Performance sur HF Spaces

CPU Basic (Gratuit)

🔒 Sécurité et Limites

Rate Limiting

WebSocket Limits

🌐 Domaine Personnalisé (Optionnel)

📈 Monitoring

Logs en Temps Réel

Metrics

🚀 Déploiement Express (TL;DR)

📚 Ressources Utiles

✅ Checklist Finale

🎊 Résultat Attendu

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