Clase 10 - Martes, 27 de octubre de 2026 (27 10 26) - Desarrollo e Implementación de sistemas en la nube
Guía de Estudio Universitaria: Desarrollo e Implementación de Sistemas en la Nube (Clase 10)
1. Introducción General
Contexto del Tema
El desarrollo de aplicaciones modernas requiere no solo la escritura de código funcional en el entorno local (localhost), sino también su correcto despliegue, integración y puesta en producción en arquitecturas basadas en la nube. En la práctica profesional e integradora de proyectos de software, es habitual separar el frontend (interfaz gráfica de usuario) del backend (lógica de negocio, servidor de API y acceso a bases de datos).
Esta sesión se enfoca en la resolución de problemas prácticos y técnicos para lograr que un backend desarrollado en Node.js con Express sea publicado en una URL pública accesible mediante la plataforma cloud Vercel, interactuando con servicios de bases de datos relacionales en la nube (Supabase) y no relacionales (MongoDB en Render), controlando el ciclo de vida del código mediante Git y GitHub.
Importancia y Relevancia
En la fase final de la materia, la integración de servicios en la nube representa el hito crítico para garantizar que los sistemas sean operativos, escalables y públicamente consumibles. Comprender los mecanismos de:
- Integración continua y despliegue continuo (CI/CD).
- Autenticación mediante tokens en herramientas de línea de comandos (CLI).
- Configuración de entornos de ejecución serverless/cloud.
- Diagnóstico de errores en producción a través de registros de logs.
- Gestión de la seguridad para evitar la exposición implícita de secretos y credenciales en repositorios públicos.
Resulta fundamental para evitar bloqueos en el desarrollo de aplicaciones web complejas.
Dinámica de la Clase y Rol Docente
Durante la sesión, ante la inasistencia recurrente del profesor titular en clases previas, la clase se estructuró como un taller eminentemente práctico de resolución de dudas bloqueantes (troubleshooting en vivo), liderado por el docente asistente para destrabar proyectos de backend y frontend que se encontraban desconectados de sus bases de datos y entornos cloud.
2. Marco Conceptual
Definición de Conceptos Clave
- Backend: Capa de acceso a datos y lógica de negocio que corre en el servidor. En la sesión se analiza una API en Node.js/Express para la gestión de turnos de una estética (
back turnos). - PaaS / Serverless Deployment (Vercel & Render): Plataformas en la nube que automatizan el despliegue de aplicaciones sin necesidad de gestionar la infraestructura subyacente. Vercel orienta su modelo al despliegue serverless a partir de archivos de entrada (entrypoints), mientras que Render permite ejecutar microservicios y contenedores de manera persistente.
- Vercel CLI (Command Line Interface): Herramienta de línea de comandos que permite gestionar proyectos, autenticarse y realizar despliegues a Vercel directamente desde la terminal de comandos del sistema.
- Archivo
**vercel.json**: Archivo de configuración estandarizado en formato JSON que le indica a la infraestructura de Vercel la versión del compilador, la ubicación del archivo servidor que actuará como punto de entrada (por ejemplo,src/server.js) y el enrutamiento de las peticiones HTTP hacia dicho archivo. - Variables de Entorno (
**.env**): Archivo local de texto donde se almacenan claves sensibles, contraseñas de bases de datos (p. ej., cadenas de conexión de Supabase), puertos y URLs privadas, separando la configuración sensible del código fuente. - Secret Protection Rules (GitHub): Reglas de seguridad automáticas implementadas en GitHub que escanean activamente los commits entrantes para detectar y rechazar el envío (push) de información confidencial (como claves privadas, cadenas de conexión a bases de datos o Access Tokens).
- Sensibilidad a Mayúsculas y Minúsculas (Case Sensitivity): Diferencia crucial entre los sistemas de archivos locales (como Windows, donde
Servicio.jsyservicio.jspueden resolverse igual) y los entornos Linux sobre los que corren los servidores en la nube (donde la diferencia de una sola mayúscula rompe la importación de módulos).
3. Desarrollo del Tema
3.1 Despliegue de un Backend Node.js en Vercel Paso a Paso
El proceso para desplegar una arquitectura backend desasociada en Vercel requiere estructurar el proyecto mediante la inclusión de archivos de configuración clave y la alineación del entorno de ejecución.
Estructura del Archivo vercel.json
Para que Vercel reconozca un servidor Node.js/Express, es necesario crear un archivo denominado vercel.json exactamente en la raíz del proyecto. Este archivo instruye a la plataforma sobre cómo manejar las peticiones entrantes:
{
"version": 2,
"builds": [
{
"src": "src/server.js",
"use": "@vercel/node"
}
],
"routes": [
{
"src": "/(.*)",
"dest": "src/server.js"
}
]
}
- Nota de arquitectura: La ruta
src/server.jsdebe coincidir de forma exacta con la ubicación del archivo principal que levanta la aplicación o servidor HTTP.
Alineación de Versiones de Node.js en package.json
Vercel utiliza versiones por defecto de Node.js (como Node 20.x). Si la máquina local utiliza una versión superior (por ejemplo, Node 24.18), es indispensable especificar la versión correspondiente dentro de la sección engines en el archivo package.json, así como asegurarse de declarar el script de inicio (start):
{
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "node src/server.js"
},
"engines": {
"node": "24.x"
}
}
Autenticación y Despliegue con Vercel CLI
- Instalación Global: Se ejecuta en la consola el comando de instalación del cliente de Vercel:
npm install -g vercel
# O de forma abreviada: npm i -g vercel
- Autenticación mediante Personal Access Tokens: En caso de que el comando estándar
vercel loginfalle debido a problemas de redirección de red, errores de resolución de endpoints o fallas de configuración OAuth en el navegador, se debe recurrir al uso de Tokens Personales:- Paso A: Acceder a la consola web de Vercel → Account Settings → Tokens.
- Paso B: Crear un nuevo token definiendo un nombre (ej.
mi compu), asignando el alcance (Scope) del proyecto correspondiente y estableciendo la expiración (No Expiration). - Paso C: Copiar el token generado e iniciar sesión en la consola local pasando el modificador
--token:
vercel --token <VALOR_DEL_TOKEN>
- Reglas de Nombrado de Proyectos en Vercel: Vercel impone restricciones estrictas sobre los nombres de los proyectos:
- Prohibido: Uso de letras mayúsculas, espacios, puntos o caracteres especiales (ej.
PP3 turnoses rechazado). - Permitido: Solo caracteres en minúsculas (lower case), números y guiones medios (ej.
back-turnos). - Acción correctiva: Si el directorio local o el nombre asignado contiene mayúsculas, se debe renombrar la carpeta del proyecto y reconfigurar el nombre en minúsculas.
- Prohibido: Uso de letras mayúsculas, espacios, puntos o caracteres especiales (ej.
- Comandos de Despliegue:
vercel: Inicia el asistente interactivo para crear o vincular el proyecto cloud localmente.vercel --prod: Ejecuta la compilación y despliegue final directo hacia el entorno de producción, generando la URL pública del backend.
3.2 Diagnóstico y Resolución de Errores en Producción
Una vez ejecutado el despliegue a producción, el estado "Deploy Complete" no garantiza que la aplicación esté funcionando correctamente a nivel de código.
Inspección de Registros de Logs
Cuando el servidor devuelve respuestas de error HTTP (por ejemplo, código 500 Server Error o incapacidad para resolver rutas), es necesario acceder a la consola de registros de producción ejecutando:
vercel logs
Sensibilidad de Archivos (Case Sensitivity)
Uno de los errores más comunes al migrar código de entornos Windows a plataformas en la nube sobre Linux es la falta de coincidencia exacta entre la declaración de importación de módulos y el nombre del archivo en el sistema.
- Ejemplo del problema observado en clase: En la línea 10 de la definición de rutas se importaba:
require('./routes/professionalServiceRoutes')(con la letra "P" mayúscula). Sin embargo, en la estructura física del proyecto, el archivo en la carpeta de rutas estaba nombrado con minúscula inicial (professionalServiceRoutes.js). - Efecto: Mientras que el servidor local en Windows ignoraba la diferencia y levantaba la API, en el entorno Linux de Vercel la aplicación colapsaba arrojando un error de tipo
Cannot find module. - Solución: Unificar estrictamente los nombres de archivos e importaciones respetando el mismo uso de mayúsculas y minúsculas (camelCase o minúsculas sostenidas).
3.3 Gestión de Seguridad de Credenciales y Manejo del Historial de Git
Bloqueo de Commits por el Escáner de Secretos de GitHub
GitHub cuenta con sistemas automatizados de protección de secretos (Secret Protection Rules). Si se intenta subir un código donde un archivo (como .env) contiene contraseñas de bases de datos (ej. credenciales de Supabase), URLs privadas o claves secretas, GitHub rechazará el git push con una violación de regla (repository rule violation / remote rejected).
Ineficacia de .gitignore a Posteriori
Agregar el archivo .env al archivo .gitignore después de haber realizado un git commit previo no resuelve el problema. La razón es que Git funciona rastreando el historial de cambios; aunque el archivo ya no esté en el directorio de trabajo actual, la clave confidencial permanece registrada dentro del historial de commits anteriores que se intenta enviar al servidor remoto.
Procedimiento de Limpieza del Historial
Para eliminar de forma definitiva la presencia de credenciales e información confidencial en el repositorio de Git, se debe seguir el siguiente procedimiento técnico:
- Creación del archivo
**.gitignore**: Asegurarse de incluir explícitamente las carpetas y archivos que no deben rastrearse:
node_modules
.env
- Reescritura o Limpieza del Historial Local de Git:
- Opción A (Línea de Comandos Básica): Desenlazar el archivo sensible rastreado mediante el comando del índice de Git:
git rm --cached .env
- Opción B (Uso de Herramientas de Reescritura de Historial): Emplear la herramienta
git filter-branch(o en su defectogit filter-repomediante entorno de ejecución en Python/PIP) para depurar la presencia de las claves en las ramas del historial. - Opción C (Reinicio del Repositorio Local en Casos Críticos): Si el historial local contiene commits donde se filtró el secreto, se puede remover la carpeta oculta
.git(comando de eliminación de directorio) y re-inicializar el repositorio desde cero mediante:
git init
git add .
git commit -m "Initial clean commit"
git branch -M main
git remote add origin <URL_DEL_REPOSITORIO>
git push -u origin main --force
3.4 Despliegue de Microservicios Backend en Render con MongoDB
Como alternativa o complemento a Vercel, en la sesión se analizó la arquitectura implementada para un microservicio independiente:
- Entorno de Despliegue: Platform as a Service (Render).
- Base de Datos: MongoDB (NoSQL alojada en la nube).
- Validación de Funcionamiento: Peticiones HTTP de prueba ejecutadas de forma exitosa mediante la herramienta de desarrollo Postman.
4. Relaciones entre Conceptos
La interacción de todas las herramientas analizadas responde a una arquitectura en capas interconectada:
[ Desarrollo Local ]
│ ├── Código Fuente (Node.js / Express)
│ ├── Configuración: vercel.json & package.json (engines 24.x)
│ └── Archivo sensible: .env (Conexión Supabase / MongoDB)
│
├─── Envíos Bloqueados / Filtrados ───► [ .gitignore ] (Excluye .env)
│ │
▼ ▼
[ GitHub (Repositorio Remoto) ] ◄── Validado por: Secret Protection Rules
│
▼ (Despliegue Automático / CLI Manual)
[ Vercel / Render (Servidores Cloud) ]
│ ├── Monitoreo: vercel logs
│ └── Normalización: Case-Sensitivity / Lowercase Names
│
▼
[ Clientes / Frontend Web / Postman ] (Peticiones Públicas HTTP/API)
Estructura de Dependencias Lógicas:
- Acceso Local ↔ CLI Vercel: Depende de la autenticación válida mediante
vercel --token. Si el token expira o carece de permisos sobre la organización, el despliegue falla. - Despliegue Cloud ↔ Sistema de Archivos: La ejecución serverless de Vercel requiere que las llamadas internas de código (
require) coincidan exactamente con la estructura de directorios en Linux (Case Sensitivity). - Repositorio Git ↔ Seguridad Cloud: Vercel e Integración Continua (CI/CD) dependen de la limpieza de GitHub. Un fallo en el
git pushcausado por la detección de secretos en.envimpide la actualización automatizada del servidor de producción.
5. Ejemplos Prácticos
Ejemplo 1: Estructuración del comando de despliegue directo por Token
Cuando falla la autenticación de Vercel por navegador web, el desarrollador ejecuta en su terminal:
# 1. Instalación del CLI global
npm install -g vercel
# 2. Login usando el Personal Access Token de la cuenta
vercel --token XxXyYzZ123456789TokenString
# 3. Respuesta de confirmación e inicio del setup
? Set up and deploy "back-turnos"? [Y/n] y
? Which scope do you want to deploy to? PP3
? Link to existing project? [y/N] n
? What's your project's name? back-turnos
? In which directory is your code located? ./
# 4. Enviar a entorno definitivo de Producción
vercel --prod
Ejemplo 2: Solución al error de importación por mayúsculas/minúsculas
- Archivo problemático (
**src/app.js**):
// ERROR EN PRODUCCIÓN (LINUX):
const professionalRoutes = require('./routes/ProfessionalServiceRoutes');
- Estructura física de carpetas real:
src/routes/professionalServiceRoutes.js(comienza con minúscula). - Solución aplicada y corregida paso a paso:
// CÓDIGO CORREGIDO Y COMPATIBLE CON LINUX / VERCEL:
const professionalRoutes = require('./routes/professionalServiceRoutes');
Una vez modificado el código en el editor local:
git add .git commit -m "Fix: correccion de mayusculas en ruta de servicios"vercel --prod- Diagnóstico de verificación ejecutando
vercel logs.
6. Errores Comunes y Confusiones
| Error / Confusión | Causa Real | Solución Técnica Directa |
Ponerle mayúsculas al nombre del proyecto en Vercel (Ej. PP3_Turnos). | Vercel restringe los nombres a minúsculas para mantener la compatibilidad con direcciones URL y DNS. | Renombrar el proyecto y el directorio a minúsculas puras (pp3-turnos o back-turnos). |
Agregar **.env** al **.gitignore** pero seguir recibiendo bloqueos de GitHub al hacer **push**. | El archivo .env fue comiteado en un commit previo y permanece en el historial implícito de Git. | Ejecutar la eliminación del caché de Git (git rm --cached .env), realizar un nuevo commit y reescribir el historial o recrear el repositorio si es necesario. |
El servidor funciona en localhost (Windows) pero da error **500** o **Module Not Found** en Vercel. | Diferencia en la sensibilidad de mayúsculas/minúsculas entre el sistema de archivos NTFS/Windows y EXT4/Linux. | Revisar detalladamente que cada require() o import coincida carácter por carácter (mayúsculas y minúsculas) con el nombre físico del archivo. |
Error de redirección en el navegador al intentar hacer **vercel login**. | Fallas de resolución en los endpoints del flujo OAuth del navegador o bloqueo de firewall local. | Crear un Personal Access Token desde Account Settings en la web de Vercel y autenticarse mediante vercel --token <TOKEN>. |
| Desajustes de versiones de Node entre la máquina local y el entorno Serverless. | Vercel corre por defecto sobre una versión de Node distinta a la local (ej. Node 20 vs Node 24). | Especificar la versión exacta de Node utilizada en la propiedad "engines": { "node": "24.x" } del package.json. |
7. Fechas Importantes y Avisos Académicos
Tras un análisis exhaustivo del material y las intervenciones docentes durante la sesión, se consolidan las siguientes indicaciones organizativas y académicas:
Calendario y Eventos Académicos
- Próxima Clase Presencial / Sincrónica:
- Fecha: Próximo martes (correspondiente al ciclo de cierre de la cursada posterior al 27/10/26).
- Tipo de Evento: Clase regular de seguimiento de proyectos finales / Taller de resolución técnica.
- Descripción: Se continuará con la revisión de proyectos prácticos de arquitectura backend/frontend y resolución de problemas de integración cloud antes de la presentación final.
- Cierre de la Materia y Evaluaciones Finales:
- Fecha: Próximas semanas (se indica explícitamente en la grabación: "ya se empieza a avecinar el final de la materia").
- Tipo de Evento: Entrega de Proyecto Final Integrador / Evaluación Final de Backend y Frontend.
- Indicaciones del Docente: Todos los equipos deben tener sus arquitecturas desasociadas (Backend desplegado en plataformas tipo Vercel o Render, conectado a bases de datos cloud como Supabase o MongoDB, e integrado con el Frontend) funcionando mediante URLs públicas.
Recordatorios y Advertencias Académicas
- Ausencia del Profesor Titular: Se remarca en la clase que el profesor titular ha tenido reiteradas ausencias, por lo cual se insta a los alumnos a aprovechar el espacio de trabajos prácticos y el soporte del docente asistente para destrabar el despliegue de sus sistemas.
- Requisito de Despliegue Obligatorio: No se aceptarán entregas finales cuya arquitectura corra únicamente en entornos locales (localhost). La aplicación de backend debe estar consumible en producción.
- Control de Seguridad en Entregas: Se advierte expresamente que ningún proyecto entregado en repositorios de GitHub debe exponer credenciales activas o contraseñas de bases de datos en sus commits.
8. Síntesis y Conclusiones
Resumen Estructurado del Contenido
La integración de un sistema backend en la nube abarca la resolución sincronizada de cuatro dimensiones técnicas:
- Configuración de la Infraestructura Serverless: Requiere la creación de
vercel.json, la especificación de motores de ejecución enpackage.jsony la correcta estructuración del script de iniciostart. - Autenticación y Despliegue por Línea de Comandos: El uso del CLI de Vercel permite un ciclo de despliegue ágil. En presencia de bloqueos en interfaces web, el uso de Access Tokens garantiza la autenticación mediante la consola.
- Compatibilidad Multiplataforma (Linux/Windows): La producción en la nube exige rigor absoluto en el nombramiento de archivos e importaciones debido a la sensibilidad a mayúsculas y minúsculas en Linux.
- Higiene en el Control de Versiones: La protección de datos confidenciales exige el uso preventivo de
.gitignoredesde el primer commit. Una vez filtrado un secreto, no basta con ignorar el archivo; se requiere la reescritura o limpieza del historial del repositorio Git.
9. Preguntas de Repaso (Modo Estudio Avanzado)
Nivel Básico
- ¿Cuál es la función del archivo
**vercel.json**en un proyecto de backend Node.js?- Respuesta: Funciona como el archivo de configuración para la infraestructura de Vercel. Especifica qué compilador o constructor usar (
@vercel/node), declara la ubicación exacta del archivo principal del servidor (por ejemplo,src/server.js) y redirige todas las rutas de peticiones HTTP salientes hacia dicho punto de entrada.
- Respuesta: Funciona como el archivo de configuración para la infraestructura de Vercel. Especifica qué compilador o constructor usar (
- ¿Por qué Vercel rechaza nombres de proyecto como
**PP3 Turnos**?- Respuesta: Vercel exige que el nombre de los proyectos esté formateado exclusivamente en letras minúsculas (lower case), números y guiones, sin espacios ni caracteres especiales, para garantizar la validez en las direcciones URL y dominios asignados.
Nivel Intermedio
- Si un servidor Node.js funciona adecuadamente en una máquina con Windows pero arroja el error
**Cannot find module**al desplegarse en Vercel, ¿cuál es la causa más probable y cómo se resuelve?- Respuesta: La causa es la sensibilidad a mayúsculas y minúsculas (Case Sensitivity) propia de los sistemas Linux sobre los que corre Vercel. Si el archivo físico se llama
serviceRoutes.jsy en el código se requiere comoServiceRoutes, Windows lo resolverá pero Linux fallará. La solución consiste en corregir la sentenciarequireoimportpara que coincida exactamente en mayúsculas y minúsculas con el nombre del archivo.
- Respuesta: La causa es la sensibilidad a mayúsculas y minúsculas (Case Sensitivity) propia de los sistemas Linux sobre los que corre Vercel. Si el archivo físico se llama
- Si el comando
**vercel login**presenta fallas de red o errores de configuración en el navegador, ¿qué alternativa técnica existe para autenticar la terminal local?- Respuesta: Se debe acceder a la plataforma web de Vercel, ir a Account Settings → Tokens, generar un Personal Access Token con los permisos necesarios, y luego ejecutar en la consola local el comando
vercel --token <VALOR_DEL_TOKEN>.
- Respuesta: Se debe acceder a la plataforma web de Vercel, ir a Account Settings → Tokens, generar un Personal Access Token con los permisos necesarios, y luego ejecutar en la consola local el comando
Nivel Avanzado
- Un desarrollador agrega el archivo
**.env**a su**.gitignore**, pero al hacer**git push**, GitHub rechaza la operación citando una violación de la regla de protección de secretos (Secret Protection Rules). Explique técnicamente por qué ocurre este fenómeno y describa los pasos para solucionarlo.- Respuesta: Ocurre porque el archivo
.envya fue incluido en ungit commitanterior al momento de agregar la regla a.gitignore. Git guarda el archivo en el historial implícito de cambios. Aunque el archivo no figure en el estado actual, GitHub escanea todo el historial de commits que se intentan subir y detecta la clave confidencial. Para resolverlo, se debe remover el archivo del índice de rastreo de Git (git rm --cached .env), eliminar los rastros de las claves del historial local de commits (mediante reescritura de historial con comandos de filtrado o reiniciando el repositorio local.git) y realizar un nuevo commit limpio antes de hacer elgit push.
- Respuesta: Ocurre porque el archivo