START_HERE.md

👋 START HERE - Déployer sur HuggingFace Spaces

Bienvenue ! Ce fichier vous guide pour déployer votre application Virtual Labo Chimique sur HuggingFace Spaces.

📍 Où Êtes-Vous ?

Vous êtes dans le dossier du projet qui contient tout ce qu'il faut pour déployer sur HuggingFace.

YOUR_PROJECT/
├── Dockerfile           ← Configuration Docker
├── server.js            ← Serveur HTTP (port 7860)
├── package.json         ← Dépendances
├── src/                 ← Code source
├── public/              ← Assets statiques
├── deploy.sh            ← Script de déploiement
│
├── 📖 QUICKSTART.md     ← ⭐ LISEZ CE FICHIER EN PREMIER
├── README.md            ← Documentation générale
├── DEPLOYMENT.md        ← Guide complet de déploiement
├── HF_CONFIG.md         ← Configuration HuggingFace
└── START_HERE.md        ← Ce fichier

🎯 Votre Objectif

Déployer cette application sur :

https://huggingface.co/spaces/rinogeek/VirtualLabo

🚀 Trois Options De Déploiement

⚡ Option 1 : Script Automatisé (PLUS FACILE)

./deploy.sh

Cela va :

1. Vérifier les fichiers
2. Tester le build Docker
3. Committer les changements
4. Pousser vers HuggingFace
5. Votre app sera live en 5-7 minutes!

🔧 Option 2 : Ligne de Commande

git init
git add .
git commit -m "Deploy: Virtual Labo Chimique"
git remote add origin https://huggingface.co/spaces/rinogeek/VirtualLabo
git push origin main

📦 Option 3 : Via Interface HuggingFace Web

1. Allez à https://huggingface.co/spaces/rinogeek/VirtualLabo
2. Settings → Linked Repo
3. Connectez votre repository GitHub/GitLab
4. Déploiement automatique

⚠️ Avant de Commencer

Vérifiez ces éléments :

• ✓ Vous avez un compte HuggingFace
• ✓ L'espace existe : https://huggingface.co/spaces/rinogeek/VirtualLabo
• ✓ Git est installé : git --version
• ✓ (Optionnel) Docker : docker --version

🎓 Guides Recommandés

Pour déployer rapidement :

1. QUICKSTART.md (5 min) ← COMMENCEZ ICI
2. DEPLOYMENT.md (guide complet)
3. HF_CONFIG.md (configuration)
4. README.md (infos générales)

🔐 Configuration des Secrets

Si votre app utilise une API (ex: Groq) :

1. Allez à Settings de l'espace
2. Cliquez sur Secrets
3. Ajoutez les clés :
   • GROQ_API_KEY=votre_clé

Elles seront disponibles automatiquement comme variables d'environnement.

🧪 Test Local (Optionnel)

Avant de déployer, testez localement :

# Build l'image Docker
npm run docker:build

# Lance le serveur
npm run docker:run

# Ouvrir : http://localhost:7860

Si ça marche ici → ça marchera sur HuggingFace ✓

📊 Fichiers Importants

Fichier	Utilité
Dockerfile	Configure le conteneur Docker
server.js	Serveur HTTP (port 7860)
package.json	Dépendances npm/bun
bun.lockb	Lock file des dépendances
.dockerignore	Exclut les fichiers inutiles
.env.example	Variables d'environnement
deploy.sh	Script de déploiement

🎮 Commandes Utiles

# Développement local
npm run dev              # Lancer le dev server

# Production
npm run build            # Builder l'app
npm run start            # Lancer le serveur prod

# Docker
npm run docker:build     # Build l'image
npm run docker:run       # Lancer le conteneur
npm run docker:compose   # Avec docker-compose

# Déploiement
npm run deploy           # Script auto
./deploy.sh              # Même chose

📝 Checklist Avant Déploiement

• Git est configuré
• Les fichiers de configuration sont présents
• Le port 7860 est configuré (✓ déjà fait)
• npm run build fonctionne localement
• Docker fonctionne localement (optionnel)
• Vous avez les secrets (si nécessaire)
• L'espace HuggingFace existe

🚀 Démarrer Maintenant

La Plus Rapide (Recommandée)

# 1. Préparer
git init
git add .
git commit -m "Deploy Virtual Labo"

# 2. Configurer le remote
git remote add origin https://huggingface.co/spaces/rinogeek/VirtualLabo

# 3. Déployer
git push origin main

# Attendez 3-5 minutes → App live! 🎉

La Plus Facile (Avec Script)

./deploy.sh
# Suivre les instructions

⏱️ Temps d'Attente

Étape	Temps
Push vers HuggingFace	30 sec
Build Docker	3-7 min
Démarrage du serveur	1 min
TOTAL	5-10 min

Après cela : L'app est live! ✓

📊 Monitoring

Pour voir ce qui se passe :

1. Allez à https://huggingface.co/spaces/rinogeek/VirtualLabo
2. Cherchez le badge de status (en haut à droite)
3. Cliquez sur Build logs pour les détails

Statuts Possibles

• 🟢 Running : App live et prête
• 🟡 Building : Compilation en cours
• 🔴 Error : Quelque chose s'est mal passé
• ⚪ Stopped : App inactive (peut redémarrer)

🆘 Ça Pète ?

L'app ne démarre pas

1. Consultez les logs : Space → Build logs
2. Cherchez les erreurs
3. Comparez avec DEPLOYMENT.md#dépannage

Le build prend trop longtemps

Normal ! Premier build = 5-10 min.

Mises à jour suivantes = 2-3 min (cache).

Erreur "Application Health Check Failed"

Augmentez le timeout ou vérifiez que le serveur démarre.

📞 Besoin d'Aide?

1. Guide complet : DEPLOYMENT.md
2. Configuration : HF_CONFIG.md
3. Docs HuggingFace : https://huggingface.co/spaces/docs
4. Docker Docs : https://docs.docker.com

✅ Vous Êtes Prêt!

Choisissez une option et c'est parti :

# Option 1 : Quickstart (Recommandé)
./deploy.sh

# Option 2 : Manuel
git init && git add . && git commit -m "Deploy" && \
git remote add origin https://huggingface.co/spaces/rinogeek/VirtualLabo && \
git push origin main

🎉 Bravo!

Après le déploiement, vous aurez :

• ✅ Une app live sur HuggingFace Spaces
• ✅ URL publique : https://huggingface.co/spaces/rinogeek/VirtualLabo
• ✅ Mise à jour facile via git push
• ✅ Scaling automatique
• ✅ CORS et sécurité intégrés

---

Navigation

• ⭐ Commencez par : QUICKSTART.md
• 📖 Guide complet : DEPLOYMENT.md
• ⚙️ Configuration : HF_CONFIG.md
• 📚 Info générale : README.md

---

Vous êtes maintenant prêt à déployer ! Bonne chance! 🚀