INSTRUCCIONES.md

📋 INSTRUCCIONES DE DESPLIEGUE EN HUGGINGFACE SPACES

🎯 Archivos Necesarios

Para desplegar en HuggingFace Spaces necesitas estos 5 archivos:

1. app.py - Aplicación principal (backend Python con Gradio)
2. index.html - Frontend de la aplicación
3. requirements.txt - Dependencias de Python
4. README.md - Documentación del proyecto
5. .gitignore - Archivos a ignorar en git (opcional)

🚀 PASO A PASO: Despliegue en HuggingFace

Paso 1: Crear cuenta en HuggingFace

1. Ve a https://huggingface.co/join
2. Regístrate con tu email
3. Verifica tu cuenta

Paso 2: Crear un nuevo Space

1. Ve a https://huggingface.co/spaces
2. Click en "Create new Space" (botón azul arriba a la derecha)
3. Completa el formulario:
   • Owner: Tu usuario
   • Space name: osorno-runners (o el nombre que prefieras)
   • License: MIT
   • Select the Space SDK: Selecciona Gradio
   • Space hardware: CPU basic (gratis) - 2 vCPU • 16 GB
   • Visibility: Public (o Private si prefieres)
4. Click en "Create Space"

Paso 3: Subir archivos

Opción A: Mediante la interfaz web (Recomendado para principiantes)

1. Una vez creado el Space, verás la pantalla principal
2. Click en la pestaña "Files"
3. Click en "Add file" → "Upload files"
4. Arrastra o selecciona los 5 archivos:
   • app.py
   • index.html
   • requirements.txt
   • README.md
   • .gitignore (opcional)
5. Agrega un mensaje de commit: "Initial commit"
6. Click en "Commit to main"

Opción B: Mediante Git (Para usuarios avanzados)

# 1. Clonar el repositorio del Space
git clone https://huggingface.co/spaces/TU_USUARIO/osorno-runners
cd osorno-runners

# 2. Copiar los archivos del proyecto
cp /ruta/a/los/archivos/* .

# 3. Agregar y hacer commit
git add .
git commit -m "Initial commit: Osorno Runners v1.0"

# 4. Push a HuggingFace
git push

Paso 4: Esperar el despliegue

1. HuggingFace detectará automáticamente que es una app Gradio
2. Instalará las dependencias de requirements.txt
3. Ejecutará app.py
4. En 1-3 minutos verás tu aplicación corriendo

¡Listo! Tu aplicación está en vivo 🎉

La URL será: https://huggingface.co/spaces/TU_USUARIO/osorno-runners

🔧 Verificación y Pruebas

1. Verificar que la app esté corriendo

• Deberías ver la pantalla de login
• Las credenciales por defecto funcionan:
  • USER / 123
  • ADMIN / 123

2. Probar funcionalidades básicas

• Login como ADMIN
• Crear un plan de entrenamiento de prueba
• Ver que el plan se guarde correctamente
• Cerrar sesión y volver a entrar
• Verificar que el plan sigue ahí (persistencia SQLite)

3. Verificar logs

En la pestaña "Logs" del Space puedes ver:

🚀 Iniciando Osorno Runners - Sistema de Entrenamiento
✅ Base de datos inicializada correctamente
✅ Usuarios por defecto creados
✅ HTML cargado correctamente
🌐 Iniciando servidor en puerto 7860

📊 Base de Datos SQLite

Ubicación

La base de datos osorno_runners.db se crea automáticamente en el directorio raíz del Space.

Persistencia

• ✅ Los datos SE MANTIENEN entre reinicios del Space
• ✅ La base de datos es persistente
• ⚠️ Si ELIMINAS el Space, pierdes todos los datos

Backup

Para hacer backup:

1. Ve a la pestaña "Files" de tu Space
2. Busca el archivo osorno_runners.db
3. Click en "Download"
4. Guarda el archivo localmente

Para restaurar:

1. Ve a "Files"
2. "Upload files"
3. Sube tu archivo osorno_runners.db

🐛 Solución de Problemas

Error: "Space failed to build"

Causa: Problema en requirements.txt o app.py

Solución:

1. Verifica que requirements.txt tenga solo: gradio==4.44.0
2. Revisa los logs para ver el error específico
3. Asegúrate que no haya errores de sintaxis en app.py

Error: "Application not responding"

Causa: El servidor no inició correctamente

Solución:

1. Ve a "Settings" → "Factory reboot" → "Reboot Space"
2. Espera 2-3 minutos
3. Si persiste, revisa los logs

Error: "index.html not found"

Causa: No se subió el archivo HTML

Solución:

1. Verifica que index.html esté en la raíz del Space
2. El nombre debe ser exacto: index.html (minúsculas)

Error de login: "Credenciales inválidas"

Causa: Base de datos no inicializada

Solución:

1. Reboot del Space
2. Verifica en logs que aparezca: "✅ Usuarios por defecto creados"

🔐 Seguridad

Cambiar contraseñas por defecto

Edita app.py, busca la función init_db() y cambia:

cursor.execute("INSERT INTO users VALUES ('USER', 'NUEVA_PASS', 'user', 'Usuario')")
cursor.execute("INSERT INTO users VALUES ('ADMIN', 'NUEVA_PASS_ADMIN', 'admin', 'Admin')")

Luego:

1. Commit los cambios
2. Reboot del Space
3. ELIMINA el archivo osorno_runners.db (si ya existía)
4. Reboot nuevamente para que se cree con las nuevas credenciales

📈 Monitoreo

Estadísticas del Space

En la página principal del Space puedes ver:

• Número de visitantes
• Uso de CPU/RAM
• Uptime

Limits del plan gratuito

• Storage: 50 GB
• RAM: 16 GB
• CPU: 2 vCPU
• Persistent storage: ✅ Sí

🚀 Mejoras Post-Despliegue

1. Personalizar README.md: Agrega capturas de pantalla
2. Agregar más usuarios: Modifica la función init_db()
3. Tema personalizado: Edita index.html y los estilos CSS
4. Analytics: Agrega Google Analytics si quieres estadísticas

📞 Soporte

Si tienes problemas:

1. Revisa los logs del Space
2. Busca en HuggingFace Community
3. Abre un issue en el repositorio

✅ Checklist Final

Antes de considerar el despliegue completo, verifica:

• El Space está en status "Running" (verde)
• Puedes hacer login con USER/123
• Puedes crear un plan como ADMIN
• El plan se guarda y persiste después de recargar
• Puedes ver los planes creados
• La exportación a PDF funciona
• Los cálculos de IMC y zonas FC son correctos

---

¡Felicidades! Tu aplicación Osorno Runners está en producción en HuggingFace Spaces 🎉🏃‍♂️

URL de ejemplo: https://huggingface.co/spaces/TU_USUARIO/osorno-runners

Comparte el link con tus usuarios y ¡a entrenar!