GestionTablets/INSTALL.md

Instalación y Configuración - GestionTablets

Versión: 1.0
Fecha: 24 de junio de 2026
Idioma: Español

---

📋 Requisitos Previos

Antes de instalar GestionTablets, asegúrate de que tu sistema cumple con los siguientes requisitos:

Sistema Operativo

• Linux (recomendado: Debian 12+, Ubuntu 22.04+)
• macOS (11+)
• Windows (10+ con WSL2 recomendado)

Dependencias del Sistema

Requisito	Versión Mínima	Cómo instalar (Debian/Ubuntu)	Notas
Python	3.13.0	sudo apt update && sudo apt install python3.13	Obligatorio
Git	2.30+	sudo apt install git	Para clonar el repositorio
curl	-	sudo apt install curl	Para instalar uv
SQLite3	3.35+	sudo apt install sqlite3	Incluido en Python

⚠️ NOTA IMPORTANTE: Este proyecto requiere Python 3.13+ debido al uso de uv como gestor de dependencias.

---

🚀 Instalación Rápida

Ejecuta estos comandos en tu terminal:

# 1. Clonar el repositorio
git clone http://hq.ijuanes.ovh:3333/ijuanes/GestionTablets.git
cd GestionTablets

# 2. Ejecutar el script de configuración (requiere permisos de ejecución)
chmod +x setup.sh
./setup.sh

El script setup.sh se encargará de:

• Instalar uv si no está presente
• Crear un entorno virtual aislado
• Instalar todas las dependencias Python
• Inicializar la base de datos
• Configurar las variables de entorno básicas

---

🔧 Instalación Manual (sin setup.sh)

Si prefieres instalar manualmente, sigue estos pasos:

1. Instalar uv (gestor de paquetes de Python)

# Instalar uv (Astral)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Añadir uv al PATH (para la sesión actual)
export PATH="$HOME/.local/bin:$PATH"

# Verificar instalación
uv --version

Nota: Si usas zsh, añade export PATH="$HOME/.local/bin:$PATH" a tu ~/.zshrc. Si usas bash, añádelo a tu ~/.bashrc o ~/.bash_profile.

2. Crear entorno virtual

# Crear entorno virtual con uv
uv venv .venv

# Activar el entorno virtual
source .venv/bin/activate

3. Instalar dependencias

# Instalar dependencias desde requirements.txt
uv pip install -r requirements.txt

4. Inicializar la base de datos

# Inicializar la base de datos SQLite
python3 -c "from app import init_db; init_db(); print('✅ Base de datos inicializada')"

5. Configurar variables de entorno

Crea un archivo .env en el directorio raíz del proyecto:

# Copiar el archivo de ejemplo (si existe)
cp .env.example .env

# O crear manualmente
cat > .env << EOF
# Configuración de Flask
FLASK_APP=app.py
FLASK_ENV=production

# Clave secreta (generar una nueva con: openssl rand -hex 32)
SECRET_KEY=tu_clave_secreta_aqui_cambiarla

# Base de datos (opcional, por defecto: tablets.db)
DATABASE=tablets.db
EOF

⚠️ IMPORTANTE: Genera una clave secreta segura:

openssl rand -hex 32

---

🏃‍♂️ Ejecución

Desarrollo

# Activar el entorno virtual (si no lo está)
source .venv/bin/activate

# Ejecutar la aplicación en modo desarrollo
python3 app.py

La aplicación estará disponible en: http://localhost:5000

Producción

Para producción, se recomienda usar Waitress (ya incluido en requirements.txt):

# Activar el entorno virtual
source .venv/bin/activate

# Ejecutar con Waitress (más robusto que el servidor de desarrollo)
waitress-serve --port=8080 app:app

La aplicación estará disponible en: http://localhost:8080

Nota: Para producción real, considera:

• Usar un proxy inverso (Nginx, Apache)
• Configurar HTTPS
• Establecer un dominio/IP estática

---

📦 Actualización

Para actualizar a la última versión:

# Desde el directorio del proyecto
git pull origin develop

# Actualizar dependencias (opcional, si requirements.txt ha cambiado)
source .venv/bin/activate
uv pip install -r requirements.txt --upgrade

# Reiniciar la aplicación
# (Ctrl+C para detener, luego vuelve a ejecutar)

---

🔄 Migración de Base de Datos

Si ya tienes una base de datos existente y necesitas migrar a la nueva estructura (con soporte para alumnos):

# Hacer backup de la base de datos actual
cp tablets.db tablets.db.backup

# Ejecutar el script de migración
python3 scripts/migrate_database.py

# Importar datos de alumnos (si tienes un CSV)
python3 scripts/import_students.py Datos_programa.csv --verbose

Nota: El script de migración crea automáticamente un backup antes de realizar cambios.

---

🧪 Ejecución de Pruebas

Para verificar que todo funciona correctamente:

# Activar el entorno virtual
source .venv/bin/activate

# Ejecutar todas las pruebas
python3 -m pytest

# Ejecutar con cobertura de código
python3 -m pytest --cov=app --cov-report=term

# Ejecutar pruebas específicas
python3 -m pytest tests/test_import.py -v

Deberías ver: 46 passed, 1 warning in X.XXs

---

📂 Estructura del Proyecto

GestionTablets/
├── app.py                          # Aplicación Flask principal
├── requirements.txt                # Dependencias Python
├── setup.sh                        # Script de configuración automática
├── INSTALL.md                      # Este documento
├── .env.example                    # Plantilla de variables de entorno
├── .gitignore                      # Archivos ignorados por Git
├── tablets.db                      # Base de datos SQLite (generada)
├── docs/
│   └── DATABASE_SCHEMA_SPECIFICATION.md  # Esquema de la base de datos
├── scripts/
│   ├── import_students.py         # Importación de alumnos desde CSV
│   └── migrate_database.py        # Migración de base de datos
├── templates/                      # Plantillas HTML (Jinja2)
│   ├── base.html                  # Plantilla base
│   ├── index.html                 # Página principal
│   ├── students.html              # Lista de alumnos
│   └── ...
└── translations/                  # Archivos de traducción (i18n)

---

🛠️ Solución de Problemas

Problema: "Command 'uv' not found"

Solución:

# Instalar uv manualmente
curl -LsSf https://astral.sh/uv/install.sh | sh

# Añadir al PATH
export PATH="$HOME/.local/bin:$PATH"

# Verificar
uv --version

Problema: "Python 3.13 not found"

Solución:

# Instalar Python 3.13 en Debian/Ubuntu
sudo apt update
sudo apt install python3.13 python3.13-venv python3.13-dev

# Verificar
python3.13 --version

Problema: "ModuleNotFoundError: No module named 'flask'"

Solución:

# Asegúrate de que el entorno virtual está activado
source .venv/bin/activate

# Instalar dependencias
uv pip install -r requirements.txt

Problema: "Permission denied" al ejecutar setup.sh

Solución:

# Dar permisos de ejecución
chmod +x setup.sh

# Ejecutar
./setup.sh

Problema: La base de datos no se inicializa

Solución:

# Forzar inicialización manual
python3 -c "from app import init_db; init_db()"

---

📝 Variables de Entorno

Variable	Valor por Defecto	Descripción	Requerida
FLASK_APP	app.py	Archivo principal de Flask	No
FLASK_ENV	production	Entorno de Flask (development o production)	No
SECRET_KEY	-	Clave secreta para sesiones (¡genera una nueva!)	Sí
DATABASE	tablets.db	Ruta a la base de datos SQLite	No
PORT	5000	Puerto del servidor (solo para desarrollo)	No

---

🔒 Seguridad

Clave Secreta

• Nunca uses la clave secreta por defecto en producción.
• Genera una nueva con: openssl rand -hex 32
• Guárdala en .env (este archivo no debe comitearse a Git)

Base de Datos

• El archivo tablets.db contiene todos los datos del sistema.
• Haz backups regulares: cp tablets.db tablets.db.backup
• No expongas el archivo públicamente.

Acceso a la Aplicación

• Actualmente, la aplicación no tiene autenticación.
• Recomendación para producción:
  • Usa un proxy inverso con autenticación (Nginx + Basic Auth)
  • O implementa autenticación en Flask (ver propuestas de mejora)

---

📞 Soporte

Si encuentras problemas:

1. Revisa esta documentación (INSTALL.md)
2. Consulta los logs de la aplicación
3. Verifica los requisitos (Python 3.13+, uv, etc.)
4. Contacta al administrador del sistema (ijuanes)

---

📚 Documentación Adicional

• DOCUMENTACION_RECAPITULACION.md - Recapitulación técnica completa
• IMPLEMENTATION_SUMMARY.md - Resumen de implementación
• docs/DATABASE_SCHEMA_SPECIFICATION.md - Esquema detallado de la base de datos