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:

```bash
# 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)

```bash
# 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

```bash
# Crear entorno virtual con uv
uv venv .venv

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

### 3. Instalar dependencias

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

### 4. Inicializar la base de datos

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

```bash
# 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:
> ```bash
> openssl rand -hex 32
> ```

---

## 🏃‍♂️ Ejecución

### Desarrollo

```bash
# 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`):

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

```bash
# 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):

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

```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Dar permisos de ejecución
chmod +x setup.sh

# Ejecutar
./setup.sh
```

### Problema: La base de datos no se inicializa

**Solución:**
```bash
# 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](DOCUMENTACION_RECAPITULACION.md) - Recapitulación técnica completa
- [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) - Resumen de implementación
- [docs/DATABASE_SCHEMA_SPECIFICATION.md](docs/DATABASE_SCHEMA_SPECIFICATION.md) - Esquema detallado de la base de datos