From d909006a0185c4ad254411df7823bc135765ceac Mon Sep 17 00:00:00 2001 From: ijuanes Date: Wed, 24 Jun 2026 22:16:35 +0100 Subject: [PATCH] Add production deployment files: - INSTALL.md: Complete installation guide in Spanish - setup.sh: Automatic setup script for dependencies - .env.example: Environment variables template - Updated requirements.txt and .gitignore --- .env.example | 17 +++ .gitignore | 21 ++- INSTALL.md | 354 +++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 10 +- setup.sh | 164 ++++++++++++++++++++++ 5 files changed, 560 insertions(+), 6 deletions(-) create mode 100644 .env.example create mode 100644 INSTALL.md create mode 100755 setup.sh diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..6540c16 --- /dev/null +++ b/.env.example @@ -0,0 +1,17 @@ +# Configuración de ejemplo para GestionTablets +# COPIA este archivo a .env y ajusta los valores según tu entorno + +# Configuración de Flask +FLASK_APP=app.py +FLASK_ENV=development + +# Clave secreta para sesiones y CSRF +# GENERA UNA NUEVA CON: openssl rand -hex 32 +# O en Python: python3 -c "import secrets; print(secrets.token_hex(32))" +SECRET_KEY=cambiar_esta_clave_por_una_segura_en_produccion + +# Configuración de la base de datos +DATABASE=tablets.db + +# Puerto del servidor (solo para desarrollo) +PORT=5000 diff --git a/.gitignore b/.gitignore index ec5f329..3beb5d8 100644 --- a/.gitignore +++ b/.gitignore @@ -13,9 +13,10 @@ wheels/ *.db *.db-journal -# Project-specific -notes_development/ -.vibe/ +# Environment files +.env +.env.local +.env.*.local # IDE/Editor .idea/ @@ -29,3 +30,17 @@ Thumbs.db # Python .python-version + +# Project-specific +notes_development/ +.vibe/ + +# Logs and temporary files +*.log +*.tmp + +# Test coverage +.htmlcov/ +.coverage + +# Local configuration diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..2de19d4 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,354 @@ +# 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 diff --git a/requirements.txt b/requirements.txt index 0c8588e..7cac1cc 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,16 +1,20 @@ # Core dependencies Flask==2.3.3 Flask-Babel==2.0.0 +python-dotenv==1.0.0 # Database -sqlite3 # Built-in, but listed for clarity +# sqlite3 is built-in with Python # For CSV processing -python-dotenv==1.0.0 +# No additional dependencies needed (csv is built-in) # For development/testing pytest==7.4.0 pytest-cov==4.1.0 -# For running the application +# For running the application in production waitress==2.1.2 # Production WSGI server + +# For production deployment (optional) +# gunicorn==21.2.0 # Alternative WSGI server diff --git a/setup.sh b/setup.sh new file mode 100755 index 0000000..925a000 --- /dev/null +++ b/setup.sh @@ -0,0 +1,164 @@ +#!/bin/bash +# setup.sh - Script de configuración automática para GestionTablets +# Este script instala las dependencias necesarias y configura el entorno + +set -e # Salir en caso de error + +# Colores para salida +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Función para imprimir mensajes +print_status() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +print_success() { + echo -e "${GREEN}[OK]${NC} $1" +} + +print_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +print_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +# Verificar que estamos en el directorio correcto +if [ ! -f "app.py" ]; then + print_error "No se encuentra app.py. Ejecuta este script desde el directorio raíz de GestionTablets." + exit 1 +fi + +# 1. Verificar Python 3.13+ +print_status "Verificando versión de Python..." +PYTHON_VERSION=$(python3 --version 2>&1 | cut -d' ' -f2 | cut -d'.' -f1-2) +if [ "$PYTHON_VERSION" != "3.13" ]; then + print_error "Se requiere Python 3.13. Encontrado: $PYTHON_VERSION" + print_status "Instala Python 3.13 con: sudo apt install python3.13" + exit 1 +fi +print_success "Python 3.13+ detectado" + +# 2. Instalar uv si no está presente +print_status "Verificando uv..." +if ! command -v uv &> /dev/null; then + print_status "Instalando uv (Astral)..." + if ! curl -LsSf https://astral.sh/uv/install.sh | sh; then + print_error "No se pudo instalar uv. Verifica tu conexión a internet y que curl está instalado." + exit 1 + fi + # Añadir uv al PATH para esta sesión + export PATH="$HOME/.local/bin:$PATH" + print_success "uv instalado correctamente" +else + print_success "uv ya está instalado" +fi + +# Verificar versión de uv +UV_VERSION=$(uv --version 2>&1) +print_status "Versión de uv: $UV_VERSION" + +# 3. Crear entorno virtual +print_status "Creando entorno virtual..." +if [ -d ".venv" ]; then + print_warning "El entorno virtual .venv ya existe. Usando el existente." +else + if ! uv venv .venv; then + print_error "No se pudo crear el entorno virtual" + exit 1 + fi + print_success "Entorno virtual creado" +fi + +# Activar el entorno virtual +print_status "Activando entorno virtual..." +source .venv/bin/activate + +# 4. Instalar dependencias +print_status "Instalando dependencias desde requirements.txt..." +if [ -f "requirements.txt" ]; then + if ! uv pip install -r requirements.txt; then + print_error "No se pudieron instalar las dependencias" + exit 1 + fi + print_success "Dependencias instaladas" +else + print_error "No se encuentra requirements.txt" + exit 1 +fi + +# 5. Inicializar base de datos +print_status "Inicializando base de datos..." +if [ ! -f "tablets.db" ]; then + if python3 -c "from app import init_db; init_db(); print('Base de datos inicializada')" 2>&1; then + print_success "Base de datos inicializada" + else + print_warning "No se pudo inicializar la base de datos automáticamente" + print_status "Puedes inicializarla manualmente con: python3 -c \"from app import init_db; init_db()\"" + fi +else + print_warning "tablets.db ya existe. No se ha sobrescrito." +fi + +# 6. Configurar variables de entorno +print_status "Configurando variables de entorno..." +if [ ! -f ".env" ]; then + # Generar clave secreta + SECRET_KEY=$(openssl rand -hex 32 2>/dev/null || python3 -c "import secrets; print(secrets.token_hex(32))" 2>/dev/null || echo "cambiar_esta_clave_manualmente") + + cat > .env << EOF +# Configuración de Flask +FLASK_APP=app.py +FLASK_ENV=development + +# Clave secreta (¡CÁMBIALA EN PRODUCCIÓN!) +SECRET_KEY=$SECRET_KEY + +# Base de datos +DATABASE=tablets.db +EOF + print_success "Archivo .env creado con configuración básica" + print_warning "⚠️ REVISA el archivo .env y cambia la SECRET_KEY antes de usar en producción" +else + print_warning ".env ya existe. No se ha sobrescrito." +fi + +# 7. Crear .env.example si no existe +if [ ! -f ".env.example" ]; then + cp .env .env.example 2>/dev/null || true + print_status "Creado .env.example" +fi + +# 8. Verificar instalación +print_status "Verificando instalación..." +print_status "Comprobando importación de Flask..." +python3 -c "import flask; print(f'Flask versión: {flask.__version__}')" 2>&1 + +print_status "Comprobando importación de la aplicación..." +python3 -c "import app; print('Aplicación importada correctamente')" 2>&1 + +# 9. Instrucciones finales +echo "" +print_success "==========================================" +print_success "¡Configuración completada con éxito!" +print_success "==========================================" +echo "" +print_status "Para ejecutar la aplicación en desarrollo:" +echo " 1. Activa el entorno virtual: source .venv/bin/activate" +echo " 2. Ejecuta la aplicación: python3 app.py" +echo "" +print_status "La aplicación estará disponible en: http://localhost:5000" +echo "" +print_status "Para producción, usa Waitress:" +echo " waitress-serve --port=8080 app:app" +echo "" +print_warning "⚠️ NO OLVIDES:" +print_warning " - Revisar y cambiar SECRET_KEY en .env" +print_warning " - Configurar FLASK_ENV=production para producción" +print_warning " - Hacer backup de tablets.db regularmente" +echo ""