🚀Guía de Instalación - ToLearn

Esta guía proporciona instrucciones detalladas para instalar y configurar la plataforma ToLearn en diferentes entornos.

📋 Tabla de Contenidos

• Requisitos del Sistema

• Instalación en Desarrollo

• Instalación con Docker

• Instalación en Producción

• Configuración de Base de Datos

• Configuración de Almacenamiento

• Configuración de Redis

• Variables de Entorno

• Solución de Problemas

💻 Requisitos del Sistema

Hardware Mínimo

• CPU: 2 cores

• RAM: 4 GB

• Almacenamiento: 20 GB disponibles

Hardware Recomendado (Producción)

• CPU: 4+ cores

• RAM: 8+ GB

• Almacenamiento: 50+ GB SSD

Software Requerido

Obligatorio

• Python: 3.8 o superior (recomendado 3.10+)

• PostgreSQL: 12 o superior (recomendado 14+)

• Redis: 6.0 o superior

• Git: Para clonar el repositorio

Opcional

• Docker: 20.10+ y Docker Compose 1.29+ (para instalación con contenedores)

• Node.js: 14+ (para desarrollo frontend)

• Nginx: Como proxy inverso en producción

🔧 Instalación en Desarrollo

Paso 1: Clonar el Repositorio

git clone https://github.com/dpalik500/Tolearn.git
cd Tolearn

Paso 2: Crear Entorno Virtual

Linux/MacOS

python3 -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate

Paso 3: Instalar Dependencias

# Actualizar pip
pip install --upgrade pip

# Instalar todas las dependencias
pip install -r requirements.txt

Paso 4: Configurar Variables de Entorno

Crear archivo .env en la raíz del proyecto:

# Copiar plantilla de ejemplo
cp .env.example .env

Editar .env con tus configuraciones:

# Django Settings
SECRET_KEY=tu-clave-secreta-muy-larga-y-aleatoria
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Database Configuration
DB_ENGINE=django.db.backends.postgresql
DB_NAME=tolearn_db
DB_USER=tolearn_user
DB_PASSWORD=tu_password_seguro
DB_HOST=localhost
DB_PORT=5432

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379

# AWS S3 Configuration (opcional en desarrollo)
AWS_ACCESS_KEY_ID=tu_access_key
AWS_SECRET_ACCESS_KEY=tu_secret_key
AWS_STORAGE_BUCKET_NAME=tu_bucket
AWS_S3_ENDPOINT_URL=https://s3.twcstorage.ru
AWS_S3_REGION_NAME=ru-1

# Email Configuration
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
[email protected]

# OAuth Google
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=tu_client_id
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=tu_client_secret

# Security
SECURE_SSL_REDIRECT=False
SESSION_COOKIE_SECURE=False
CSRF_COOKIE_SECURE=False

Paso 5: Configurar PostgreSQL

Instalar PostgreSQL

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib

MacOS (Homebrew):

brew install postgresql
brew services start postgresql

Windows: Descargar e instalar desde postgresql.org

Crear Base de Datos

# Acceder a PostgreSQL
sudo -u postgres psql

# Dentro de PostgreSQL
CREATE DATABASE tolearn_db;
CREATE USER tolearn_user WITH PASSWORD 'tu_password_seguro';
ALTER ROLE tolearn_user SET client_encoding TO 'utf8';
ALTER ROLE tolearn_user SET default_transaction_isolation TO 'read committed';
ALTER ROLE tolearn_user SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE tolearn_db TO tolearn_user;

# Salir
\q

Paso 6: Ejecutar Migraciones

# Aplicar migraciones
python manage.py migrate

# Crear traducciones
python manage.py compilemessages

Paso 7: Crear Superusuario

python manage.py createsuperuser

Proporciona los siguientes datos:

• Username (nombre de usuario)

• Email

• Password

Paso 8: Cargar Datos de Prueba (Opcional)

# Si existen fixtures
python manage.py loaddata initial_data.json

Paso 9: Recopilar Archivos Estáticos

python manage.py collectstatic --noinput

Paso 10: Iniciar Servidor de Desarrollo

# Servidor Django
python manage.py runserver

# En otra terminal, iniciar Redis (si no está corriendo)
redis-server

# En otra terminal, iniciar Daphne para WebSockets
daphne -b 0.0.0.0 -p 8001 testfox.asgi:application

Acceder a la plataforma en: http://localhost:8000

Panel de administración: http://localhost:8000/admin

🐳 Instalación con Docker

Requisitos Previos

• Docker Engine 20.10+

• Docker Compose 1.29+

Paso 1: Configurar Variables de Entorno

Editar docker-compose.yml y .env según sea necesario.

Paso 2: Construir y Ejecutar Contenedores

# Construir imágenes
docker-compose build

# Iniciar servicios
docker-compose up -d

Esto inicia:

• Contenedor web (Django)

• Contenedor PostgreSQL

• Contenedor Redis

Paso 3: Ejecutar Migraciones en Docker

docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py collectstatic --noinput
docker-compose exec web python manage.py createsuperuser

Paso 4: Acceder a la Aplicación

La plataforma estará disponible en: http://localhost:8000

Comandos Útiles de Docker

# Ver logs
docker-compose logs -f

# Ver logs de un servicio específico
docker-compose logs -f web

# Reiniciar servicios
docker-compose restart

# Detener servicios
docker-compose stop

# Detener y eliminar contenedores
docker-compose down

# Detener y eliminar contenedores, volúmenes y redes
docker-compose down -v

# Acceder al contenedor
docker-compose exec web bash

# Ejecutar comandos Django
docker-compose exec web python manage.py <comando>

🌐 Instalación en Producción

Requisitos Adicionales

• Dominio registrado

• Certificado SSL (Let's Encrypt recomendado)

• Servidor con Linux (Ubuntu 20.04+ recomendado)

Paso 1: Preparar el Servidor

# Actualizar sistema
sudo apt update && sudo apt upgrade -y

# Instalar dependencias del sistema
sudo apt install python3-pip python3-dev libpq-dev postgresql postgresql-contrib nginx curl git

Paso 2: Configurar PostgreSQL en Producción

# Asegurar PostgreSQL
sudo nano /etc/postgresql/14/main/pg_hba.conf

# Cambiar método de autenticación a md5
# local   all             all                                     md5
# host    all             all             127.0.0.1/32            md5

# Reiniciar PostgreSQL
sudo systemctl restart postgresql

Paso 3: Clonar Repositorio y Configurar

# Crear usuario para la aplicación
sudo adduser tolearn
sudo usermod -aG sudo tolearn
su - tolearn

# Clonar repositorio
cd /home/tolearn
git clone https://github.com/dpalik500/Tolearn.git
cd Tolearn

# Crear entorno virtual
python3 -m venv venv
source venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt
pip install gunicorn

Paso 4: Configurar Variables de Entorno de Producción

DEBUG=False
ALLOWED_HOSTS=tudominio.com,www.tudominio.com
SECRET_KEY=clave-super-secreta-aleatoria-muy-larga

# Database
DB_NAME=tolearn_production
DB_USER=tolearn_prod_user
DB_PASSWORD=password-muy-seguro
DB_HOST=localhost
DB_PORT=5432

# Security
SECURE_SSL_REDIRECT=True
SESSION_COOKIE_SECURE=True
CSRF_COOKIE_SECURE=True
SECURE_HSTS_SECONDS=31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS=True
SECURE_HSTS_PRELOAD=True

Paso 5: Configurar Gunicorn

Crear archivo de servicio systemd: /etc/systemd/system/tolearn.service

[Unit]
Description=ToLearn Gunicorn Application
After=network.target

[Service]
User=tolearn
Group=www-data
WorkingDirectory=/home/tolearn/Tolearn
Environment="PATH=/home/tolearn/Tolearn/venv/bin"
ExecStart=/home/tolearn/Tolearn/venv/bin/gunicorn --workers 4 --bind unix:/home/tolearn/Tolearn/tolearn.sock testfox.wsgi:application

[Install]
WantedBy=multi-user.target

Iniciar servicio:

sudo systemctl start tolearn
sudo systemctl enable tolearn

Paso 6: Configurar Daphne para WebSockets

Crear archivo: /etc/systemd/system/daphne.service

[Unit]
Description=ToLearn Daphne WebSocket Server
After=network.target

[Service]
User=tolearn
Group=www-data
WorkingDirectory=/home/tolearn/Tolearn
Environment="PATH=/home/tolearn/Tolearn/venv/bin"
ExecStart=/home/tolearn/Tolearn/venv/bin/daphne -u /home/tolearn/Tolearn/daphne.sock testfox.asgi:application

[Install]
WantedBy=multi-user.target

Iniciar servicio:

sudo systemctl start daphne
sudo systemctl enable daphne

Paso 7: Configurar Nginx

Crear archivo: /etc/nginx/sites-available/tolearn

upstream tolearn_app {
    server unix:/home/tolearn/Tolearn/tolearn.sock fail_timeout=0;
}

upstream tolearn_websocket {
    server unix:/home/tolearn/Tolearn/daphne.sock fail_timeout=0;
}

server {
    listen 80;
    server_name tudominio.com www.tudominio.com;
    
    # Redirigir a HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name tudominio.com www.tudominio.com;
    
    # Certificados SSL
    ssl_certificate /etc/letsencrypt/live/tudominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tudominio.com/privkey.pem;
    
    # Configuración SSL
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    
    client_max_body_size 100M;
    
    location = /favicon.ico { 
        access_log off; 
        log_not_found off; 
    }
    
    location /static/ {
        alias /home/tolearn/Tolearn/staticfiles/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    
    location /media/ {
        alias /home/tolearn/Tolearn/mediafiles/;
        expires 30d;
    }
    
    # WebSocket
    location /ws/ {
        proxy_pass http://tolearn_websocket;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location / {
        proxy_pass http://tolearn_app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Activar sitio:

sudo ln -s /etc/nginx/sites-available/tolearn /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Paso 8: Obtener Certificado SSL con Let's Encrypt

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d tudominio.com -d www.tudominio.com

Paso 9: Configurar Backup Automático

Crear script de backup: /home/tolearn/backup.sh

#!/bin/bash
BACKUP_DIR="/home/tolearn/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# Crear directorio si no existe
mkdir -p $BACKUP_DIR

# Backup de base de datos
pg_dump -U tolearn_prod_user tolearn_production > $BACKUP_DIR/db_$DATE.sql

# Backup de archivos media
tar -czf $BACKUP_DIR/media_$DATE.tar.gz /home/tolearn/Tolearn/mediafiles/

# Eliminar backups antiguos (más de 7 días)
find $BACKUP_DIR -type f -mtime +7 -delete

echo "Backup completado: $DATE"

Agregar a crontab:

chmod +x /home/tolearn/backup.sh
crontab -e

# Agregar línea para backup diario a las 2 AM
0 2 * * * /home/tolearn/backup.sh

🗄️ Configuración de Base de Datos

PostgreSQL Avanzado

Optimización para Producción

Editar /etc/postgresql/14/main/postgresql.conf:

# Memoria
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 16MB
maintenance_work_mem = 128MB

# Conexiones
max_connections = 100

# Logging
logging_collector = on
log_directory = 'pg_log'
log_filename = 'postgresql-%Y-%m-%d.log'
log_statement = 'all'
log_duration = on

Crear Índices para Mejor Rendimiento

-- Índices adicionales recomendados
CREATE INDEX idx_course_status ON courses_course(status);
CREATE INDEX idx_lesson_active ON courses_lesson(is_active);
CREATE INDEX idx_submission_student ON dashboard_submission(student_id);
CREATE INDEX idx_assignment_type ON dashboard_assignment(type);

☁️ Configuración de Almacenamiento

AWS S3 / S3 Compatible

Crear Bucket en AWS S3

# Instalar AWS CLI
pip install awscli

# Configurar credenciales
aws configure

# Crear bucket
aws s3 mb s3://tolearn-media --region us-east-1

# Configurar CORS
aws s3api put-bucket-cors --bucket tolearn-media --cors-configuration file://cors.json

Archivo cors.json:

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://tudominio.com"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3000
    }
  ]
}

Configuración en Django

En settings.py, la configuración S3 ya está incluida. Asegúrate de configurar las variables de entorno:

AWS_ACCESS_KEY_ID=tu_access_key_id
AWS_SECRET_ACCESS_KEY=tu_secret_access_key
AWS_STORAGE_BUCKET_NAME=tolearn-media
AWS_S3_REGION_NAME=us-east-1
AWS_S3_ENDPOINT_URL=https://s3.amazonaws.com

🔴 Configuración de Redis

Instalación de Redis

Ubuntu/Debian:

sudo apt install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

MacOS:

brew install redis
brew services start redis

Configuración de Redis para Producción

Editar /etc/redis/redis.conf:

# Bind a localhost solamente (seguridad)
bind 127.0.0.1

# Requerir contraseña
requirepass tu_password_redis_muy_seguro

# Persistencia
save 900 1
save 300 10
save 60 10000

# Memoria máxima
maxmemory 256mb
maxmemory-policy allkeys-lru

Reiniciar Redis:

sudo systemctl restart redis-server

Configurar Redis en Django

Actualizar .env:

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=tu_password_redis_muy_seguro

🔐 Variables de Entorno

Lista Completa de Variables

Variable	Descripción	Ejemplo	Requerido
SECRET_KEY	Clave secreta de Django	django-insecure-...	✅
DEBUG	Modo debug	True / False	✅
ALLOWED_HOSTS	Hosts permitidos	localhost,tudominio.com	✅
DB_NAME	Nombre de la base de datos	tolearn_db	✅
DB_USER	Usuario de PostgreSQL	tolearn_user	✅
DB_PASSWORD	Contraseña de la BD	password123	✅
DB_HOST	Host de PostgreSQL	localhost	✅
DB_PORT	Puerto de PostgreSQL	5432	✅
REDIS_HOST	Host de Redis	localhost	✅
REDIS_PORT	Puerto de Redis	6379	✅
REDIS_PASSWORD	Contraseña de Redis	password	❌
AWS_ACCESS_KEY_ID	AWS Access Key	AKIAIOSFODNN7EXAMPLE	⚠️
AWS_SECRET_ACCESS_KEY	AWS Secret Key	wJalrXUtnFEMI/...	⚠️
AWS_STORAGE_BUCKET_NAME	Nombre del bucket S3	tolearn-media	⚠️
EMAIL_HOST	Servidor SMTP	smtp.gmail.com	❌
EMAIL_PORT	Puerto SMTP	587	❌
EMAIL_HOST_USER	Usuario de email	[email protected]	❌
EMAIL_HOST_PASSWORD	Contraseña de email	password	❌

⚠️ = Requerido para funcionalidad específica

Generar SECRET_KEY Segura

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

🔧 Solución de Problemas

Error: "No module named 'psycopg2'"

# Instalar dependencias del sistema
sudo apt-get install libpq-dev python3-dev

# Reinstalar psycopg2
pip install psycopg2-binary

Error: "FATAL: Peer authentication failed"

Editar /etc/postgresql/14/main/pg_hba.conf:

# Cambiar de 'peer' a 'md5'
local   all             all                                     md5

Reiniciar PostgreSQL:

sudo systemctl restart postgresql

Error: "Redis connection refused"

# Verificar estado de Redis
sudo systemctl status redis-server

# Iniciar Redis si está detenido
sudo systemctl start redis-server

# Verificar puerto
sudo netstat -tlnp | grep redis

Error: "Permission denied" en archivos estáticos

# Corregir permisos
sudo chown -R tolearn:www-data /home/tolearn/Tolearn
sudo chmod -R 755 /home/tolearn/Tolearn
sudo chmod -R 775 /home/tolearn/Tolearn/staticfiles
sudo chmod -R 775 /home/tolearn/Tolearn/mediafiles

Error: "502 Bad Gateway" en Nginx

# Verificar logs
sudo tail -f /var/log/nginx/error.log

# Verificar servicios
sudo systemctl status tolearn
sudo systemctl status daphne

# Reiniciar servicios
sudo systemctl restart tolearn daphne nginx

Error de Migraciones

# Ver estado de migraciones
python manage.py showmigrations

# Hacer fake de migración problemática
python manage.py migrate --fake app_name migration_name

# Revertir migraciones
python manage.py migrate app_name zero
python manage.py migrate app_name

Limpiar Base de Datos y Reiniciar

# ADVERTENCIA: Esto eliminará todos los datos
python manage.py flush

# Recrear migraciones
find . -path "*/migrations/*.py" -not -name "__init__.py" -delete
find . -path "*/migrations/*.pyc" -delete
python manage.py makemigrations
python manage.py migrate

📚 Recursos Adicionales

• Documentación de Django

• Documentación de PostgreSQL

• Documentación de Redis

• Guía de Despliegue de Django

• Guía de Seguridad de Django

✅ Checklist de Instalación

• Python 3.8+ instalado

• PostgreSQL instalado y configurado

• Redis instalado y corriendo

• Repositorio clonado

• Entorno virtual creado y activado

• Dependencias instaladas

• Archivo .env configurado

• Base de datos creada

• Migraciones ejecutadas

• Superusuario creado

• Archivos estáticos recopilados

• Servidor de desarrollo funcionando

• (Producción) Gunicorn configurado

• (Producción) Nginx configurado

• (Producción) SSL configurado

• (Producción) Backups configurados

---

¿Necesitas ayuda? Consulta la Guía de Desarrollo o abre un issue en GitHub.