dashboard-leads/deploy/DEPLOYMENT_GUIDE_UBUNTU.md

Guía de Despliegue en Ubuntu Server (Dashboard Leads)

Esta guía explica el proceso paso a paso para desplegar la aplicación Dashboard Leads (Frontend React + Vite y Backend FastAPI) en un servidor Ubuntu Server 20.04 / 22.04 / 24.04 LTS.

---

1. Requisitos Previos en el Servidor Ubuntu

Conéctate por SSH a tu servidor e instala los paquetes necesarios:

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-pip python3-venv nodejs npm nginx certbot python3-certbot-nginx git

(Opcional: Si requieres conectar a SQL Server mediante pyodbc en Ubuntu, instala msodbcsql18 y unixodbc-dev).

---

2. Estructura de Directorios en el Servidor

Crea el directorio del proyecto y otorga permisos al usuario actual (ejemplo: ubuntu):

sudo mkdir -p /var/www/dashboard-leads
sudo chown -R $USER:$USER /var/www/dashboard-leads

Sube los archivos del proyecto a /var/www/dashboard-leads/ (o clónalos mediante git).

---

3. Configuración del Backend (FastAPI)

1. Ve a la carpeta backend:

   cd /var/www/dashboard-leads/backend
   

2. Crea el entorno virtual e instala dependencias:

   python3 -m venv venv
   source venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt
   

3. Configura las variables de entorno .env:

   • Copia la plantilla .env.example:

     cp .env.example .env
     

   • Edita las credenciales reales de forma segura:

     nano .env
     

   • Verifica que la variable CORS_ORIGINS contenga tus dominios:

     CORS_ORIGINS=https://dashboard-leads.escueladerefrigeracion.lat,http://dashboard-leads.escueladerefrigeracion.lat,http://api-leads.escueladerefrigeracion.lat
     

4. Prueba la ejecución manual del backend:

   uvicorn main:app --host 127.0.0.1 --port 8001
   

   (Presiona Ctrl + C para detener después de verificar).

---

4. Configuración del Servicio Systemd para Backend

1. Copia el archivo de servicio dashboard-leads-backend.service:

   sudo cp /var/www/dashboard-leads/deploy/dashboard-leads-backend.service /etc/systemd/system/
   

2. Recarga systemd, inicia y habilita el servicio:

   sudo systemctl daemon-reload
   sudo systemctl start dashboard-leads-backend
   sudo systemctl enable dashboard-leads-backend
   

3. Revisa el estado del servicio:

   sudo systemctl status dashboard-leads-backend
   

---

5. Configuración y Compilación del Frontend (React + Vite)

1. Ve a la carpeta frontend:

   cd /var/www/dashboard-leads/frontend
   

2. Configura la variable de entorno en .env:

   cp .env.example .env
   nano .env
   

   Asegúrate de que contenga la URL del backend:

   VITE_API_BASE_URL=https://api-leads.escueladerefrigeracion.lat
   

   (Recomendado usar HTTPS para evitar advertencias de Mixed Content en el navegador).

3. Instala dependencias y genera la build de producción:

   npm install
   npm run build
   

   Esto generará los archivos finales en /var/www/dashboard-leads/frontend/dist.

---

6. Configuración de Nginx

1. Copia el archivo de configuración de Nginx:

   sudo cp /var/www/dashboard-leads/deploy/nginx-leads.conf /etc/nginx/sites-available/leads.conf
   

2. Crea el enlace simbólico para activarlo:

   sudo ln -s /etc/nginx/sites-available/leads.conf /etc/nginx/sites-enabled/
   

3. Prueba la sintaxis de Nginx y recárgalo:

   sudo nginx -t
   sudo systemctl reload nginx
   

---

7. Configuración de Certificados SSL (HTTPS Gratis con Certbot)

Para habilitar SSL en ambos dominios y proteger las transmisiones:

sudo certbot --nginx -d dashboard-leads.escueladerefrigeracion.lat -d api-leads.escueladerefrigeracion.lat

Certbot actualizará automáticamente la configuración de Nginx para redirigir todo el tráfico a HTTPS de forma segura.

---

8. Mantenimiento y Comandos Útiles

• Ver logs del Backend:

  journalctl -u dashboard-leads-backend -f
  

• Reiniciar el Backend:

  sudo systemctl restart dashboard-leads-backend
  

• Actualizar cambios en Frontend:

  cd /var/www/dashboard-leads/frontend
  npm run build