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
This commit is contained in:
ijuanes
parent
fe42de5bfa
commit
a5d94364a7
5 changed files with 560 additions and 6 deletions
17
.env.example
Normal file
17
.env.example
Normal file
|
|
@ -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
|
||||
21
.gitignore
vendored
21
.gitignore
vendored
|
|
@ -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
|
||||
|
|
|
|||
354
INSTALL.md
Normal file
354
INSTALL.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
164
setup.sh
Executable file
164
setup.sh
Executable file
|
|
@ -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 ""
|
||||
Loading…
Add table
Add a link
Reference in a new issue