Bugs de Producción: Cold Start, el Cuerpo Vacío del SPA y la configuración de nginx
Este artículo técnico aborda el problema del "cold start" en una aplicación SPA (Single Page Application) desplegada en Cloud Run, donde la primera carga tras un período de inactividad es excesivamente lenta. Se identifican tres causas principales: el escalado a cero de Cloud Run, el bloqueo del renderizado por una llamada a la API y la falta de un mecanismo de "warm-up". Se implementan soluciones como mantener una instancia activa en Cloud Run, desacoplar el contenido estático del estado de carga y usar `--cpu-boost`. Aprenderás a optimizar el rendimiento de tu SPA y mejorar la experiencia de

Problema 1: La Página Se Queda Pegada (Cold Start)
Síntoma
Después de varios minutos sin visitas, la primera carga de la página mostraba un spinner indefinido. No un error explícito — solo la aplicación cargando sin avanzar, o cargando extremadamente lento (15-30 segundos). Si se esperaba lo suficiente, eventualmente el contenido aparecía.
Diagnóstico: Tres Causas Anidadas
Causa 1: Cloud Run escala a cero
Cloud Run por defecto configura --min-instances 0. Cuando no hay tráfico durante un período, la plataforma apaga todas las instancias del contenedor para ahorrar recursos. Al llegar la siguiente request, Cloud Run tiene que:
- Deserializar la imagen Docker
- Inicializar el contenedor
- Arrancar Gunicorn
- Ejecutar las migraciones pendientes (el
CMDdel backend incluyemigrate --noinput) - Recién entonces responder la request
Este proceso tarda entre 8 y 20 segundos dependiendo del estado del sistema. Durante ese tiempo, todas las requests entrantes esperan en cola.
Causa 2: Home.js gateaba TODO el contenido detrás del estado de carga
Esta fue la causa más importante desde la perspectiva del usuario. El componente Home.js tenía la siguiente estructura:
// Home.js — ANTES del fix
const [loading, setLoading] = useState(true);
const [loadError, setLoadError] = useState(false);
useEffect(() => {
const fetchTags = async () => {
setLoading(true);
try {
const response = await getTags();
setTags(response.data.results || []);
} catch (err) {
setLoadError(true);
} finally {
setLoading(false);
}
};
fetchTags();
}, []);
// ← TODO el JSX dentro de este condicional
return loading ? (
<Box sx={{ display: 'flex', justifyContent: 'center', mt: 8 }}>
<CircularProgress />
</Box>
) : loadError ? (
<ErrorState onRetry={() => fetchTags()} />
) : (
<>
<HeroSection />
<StatsSection />
<SkillsSection />
<FeaturedProjects />
<TagCloud tags={tags} />
<CTASection />
</>
);
El problema: el hero, las estadísticas, las competencias y los proyectos destacados son datos hardcodeados. No necesitan la API para renderizarse. Sin embargo, toda la página esperaba a que getTags() — la única llamada real a la API — completara antes de mostrar cualquier cosa.
Durante un cold start, esa llamada tarda 15-20 segundos. El usuario veía un spinner durante todo ese tiempo, aunque el 95% de los datos que necesitaba renderizar estaban hardcodeados en el bundle JS.
Causa 3: Sin warm-up proactivo del backend
No había ningún mecanismo para despertar el backend antes de que el usuario interactuara. La primera request real siempre pagaba el costo del cold start completo.
Fix: Tres Capas de Mitigación
Fix 1 — --min-instances=1 + --cpu-boost en deploy.yml
# .github/workflows/deploy.yml
- name: Deploy Backend
uses: google-github-actions/deploy-cloudrun@v2
with:
service: blog-backend
image: gcr.io/${{ env.PROJECT_ID }}/blog-backend
region: ${{ env.REGION }}
flags: |
--allow-unauthenticated
--min-instances=1
--cpu-boost
--min-instances=1 mantiene una instancia siempre activa. No hay cold start en condiciones normales.
--cpu-boost duplica la CPU disponible durante el arranque del contenedor. Si Cloud Run necesita crear nuevas instancias bajo carga (scale out), el tiempo de arranque se reduce a la mitad.
Costo: ~$0.50-2 USD/mes adicionales por mantener una instancia activa. Completamente justificado para un sitio de portafolio profesional donde la primera impresión importa.
Fix 2 — Desacoplar contenido estático del estado de carga en Home.js
// Home.js — DESPUÉS del fix
const [tags, setTags] = useState([]);
const [tagsLoading, setTagsLoading] = useState(true);
const [tagsError, setTagsError] = useState(false);
const [retryTrigger, setRetryTrigger] = useState(0);
useEffect(() => {
setTagsLoading(true);
setTagsError(false);
getTags()
.then((response) => setTags(response.data.results || []))
.catch(() => setTagsError(true))
.finally(() => setTagsLoading(false));
}, [retryTrigger]);
// El JSX ya no tiene un loading gate global
return (
<>
<HeroSection /> {/* Hardcodeado, renderiza inmediatamente */}
<StatsSection /> {/* Hardcodeado, renderiza inmediatamente */}
<SkillsSection /> {/* Hardcodeado, renderiza inmediatamente */}
<FeaturedProjects /> {/* Hardcodeado, renderiza inmediatamente */}
{/* Solo el tag cloud tiene su propio estado de carga */}
<Box sx={{ mt: 6 }}>
{tagsLoading ? (
<CircularProgress size={24} />
) : tagsError ? (
<Button onClick={() => setRetryTrigger((n) => n + 1)}>
Reintentar
</Button>
) : (
<TagCloud tags={tags} />
)}
</Box>
<CTASection /> {/* Hardcodeado, renderiza inmediatamente */}
</>
);
Ahora el hero, estadísticas, habilidades y proyectos destacados se renderizan instantáneamente — sin esperar ninguna API. Solo el tag cloud muestra un spinner mientras carga. Si la API falla, el tag cloud muestra un botón de reintento, pero toda la demás información del portafolio es visible.
Fix 3 — Warm-up proactivo del backend en client.js
// src/api/client.js
const BASE_URL = process.env.REACT_APP_API_URL || 'http://127.0.0.1:8000/api';
let _backendReady = false;
/** Whether the backend has responded successfully at least once */
export const isBackendReady = () => _backendReady;
// Fire-and-forget: pings /healthz al cargar el módulo
(function warmUpBackend() {
const healthUrl = BASE_URL.replace(/\/api\/?$/, '') + '/healthz';
fetch(healthUrl, { mode: 'cors', cache: 'no-store' })
.then((r) => { if (r.ok) _backendReady = true; })
.catch(() => { /* cold start — will retry on first real API call */ });
})();
Cuando el módulo client.js se importa (en el primer render de cualquier componente que use la API), se dispara inmediatamente un ping fire-and-forget a /healthz. Si el backend está dormido, esto inicia el proceso de arranque antes de que el usuario haga clic en nada. El tiempo ganado depende de cuándo se carga el módulo vs cuándo el usuario interactúa, pero en la práctica puede reducir la latencia percibida en varios segundos.
Problema 2: El Cuerpo Vacío del SPA (SEO y Social Previews)
El Contexto: Por Qué No Hay Pre-rendering
En el Post 11 documenté en detalle por qué react-snap fue eliminado del pipeline: MUI genera requestAnimationFrame loops infinitos, framer-motion hace lo mismo, y cualquier página que haga API calls al montar cuelga Puppeteer indefinidamente. Después de 8 builds fallidos, react-snap fue reemplazado por un script de Node (generate-seo.js) que inyecta meta tags en el <head> durante el build.
Pero la historia no terminó ahí. El script original solo tocaba el <head>. El <body> seguía siendo:
<div id="root"></div>
El Problema con <div id="root"></div> Vacío
Un crawler (Googlebot, Twitter Card checker, LinkedIn scraper, WhatsApp) que visita hectorgarrido.cl recibe este HTML:
<!DOCTYPE html>
<html>
<head>
<title>Héctor Garrido Henríquez | Data Scientist</title>
<meta name="description" content="Portafolio profesional..." />
<!-- meta tags perfectos aquí -->
</head>
<body>
<div id="root"></div>
<script src="/static/js/main.abc123.js"></script>
</body>
</html>
Los meta tags en <head> son correctos. Pero el <body> no tiene contenido visible. Para crawlers que no ejecutan JavaScript (la mayoría de los scrapers de redes sociales, bots de búsqueda de segunda calidad, y herramientas de Preview), la página está vacía.
Google Indexing Tool y otros validadores también marcan esto como "contenido no renderizado" aunque los meta tags estén bien.
La Solución: Inyectar Body HTML en Build Time
El enfoque fue extender generate-seo.js para que además de modificar el <head>, inyecte HTML visible dentro de <div id="root">. Este HTML es lo que ven los crawlers. React lo reemplaza completamente cuando el JS carga — no hay conflicto porque React sobrescribe el innerHTML de #root al montar.
// generate-seo.js — función generatePage() extendida
function generatePage(template, { title, description, canonical, image, type, jsonLd, bodyHtml }) {
let html = template;
// ... (meta tags, og, canonical, json-ld como antes)
// Pre-rendered body content — React lo reemplaza al cargar
if (bodyHtml) {
html = html.replace(
'<div id="root"></div>',
`<div id="root">${bodyHtml}</div>`
);
}
return html;
}
Se crearon cuatro funciones constructoras de body HTML:
buildHomeBodyHtml() — Para la página principal
function buildHomeBodyHtml() {
return `<div style="max-width:900px;margin:0 auto;padding:40px 20px;...">
<p style="color:#ce93d8">Data Scientist · Machine Learning · Econometría Aplicada</p>
<h1>Héctor Garrido Henríquez</h1>
<p>Profesional con más de 10 años de experiencia...</p>
<nav>
<a href="/projects">Ver proyectos</a>
<a href="/cv">Mi trayectoria</a>
<a href="/contact">Contactar</a>
</nav>
<h2>Proyectos Destacados</h2>
<ul>
<li><strong>Portafolio + Motor RAG</strong> — ...</li>
<li><strong>manageDW — Data Warehouse SII</strong> — ...</li>
<li><strong>Transmisión Asimétrica de Precios</strong> — ...</li>
</ul>
<h2>Competencias clave</h2>
<p>Python · R · SQL · Machine Learning · ...</p>
</div>`;
}
buildPostBodyHtml(post) — Para cada artículo del blog
function buildPostBodyHtml(post) {
const date = new Date(post.published_at).toLocaleDateString('es-CL', {
year: 'numeric', month: 'long', day: 'numeric'
});
const tags = post.tags.map((t) => t.name).join(' · ');
return `<article style="font-family:Lora,serif;...">
<h1>${esc(post.title)}</h1>
<p>${date} · ${post.reading_time} min de lectura</p>
<p>${tags}</p>
<p>${esc(post.excerpt)}</p>
<a href="/blog">← Volver al blog</a>
</article>`;
}
buildBlogListBodyHtml(posts) — Para la página /blog
Genera un listado de hasta 20 posts con títulos y excerpts.
buildStaticBodyHtml(title, description) — Para /cv, /contact, etc.
Título + descripción simples para páginas que no tienen contenido dinámico específico.
Impacto en el Root index.html
Un detalle clave: el index.html raíz (que sirve todas las rutas que nginx no puede resolver como archivos estáticos) ahora también tiene el HTML pre-renderizado del Home:
// generate-seo.js — al final del main()
const homeHtml = generatePage(template, {
title: 'Héctor Garrido Henríquez | Data Scientist',
description: DEFAULT_DESC,
canonical: '/',
// ...
bodyHtml: buildHomeBodyHtml(),
});
fs.writeFileSync(path.join(BUILD_DIR, 'index.html'), homeHtml);
Esto significa que cualquier ruta que nginx sirva como index.html (el fallback SPA) también tendrá contenido visible del Home en lugar de <div id="root"></div> vacío.
XSS y Seguridad
El contenido de posts del blog se inyecta escapado. La función esc() escapa &, ", < y >:
function esc(str) {
if (!str) return '';
return str
.replace(/&/g, '&')
.replace(/"/g, '"')
.replace(/</g, '<')
.replace(/>/g, '>');
}
Los campos usados (title, excerpt) son texto plano sin HTML. El contenido completo del post (Markdown/HTML) no se inyecta en el body pre-renderizado — solo el excerpt, que ya está sanitizado en el backend.
Problema 3: El Redirect que Expone el Puerto Interno de Cloud Run
Síntoma
Después de los fixes anteriores, entrar a hectorgarrido.cl funcionaba perfectamente. Pero navegar directamente a hectorgarrido.cl/ai-search (o cualquier otra ruta) dejaba la página pegada o mostraba un error. Lo curioso: si primero se cargaba el Home y luego se navegaba a /ai-search mediante los links del sitio, todo funcionaba.
El síntoma más revelador: después de un tiempo de espera, el navegador terminaba en http://hectorgarrido.cl:8080/ai-search/ — una URL con el puerto interno expuesto que nunca resuelve.
Diagnóstico: nginx + Directorios Pre-renderizados + try_files
Para entender el problema hay que ver tres piezas juntas:
Pieza 1: generate-seo.js crea directorios en el build.
Cada ruta con pre-render crea un directorio físico con su index.html:
build/
├── index.html ← Home
├── ai-search/
│ └── index.html ← /ai-search pre-rendereizado
├── blog/
│ └── index.html
├── contact/
│ └── index.html
├── cv/
│ └── index.html
└── projects/
└── index.html
Pieza 2: El fallback SPA de nginx usa try_files.
location / {
try_files $uri $uri/ /index.html;
}
Pieza 3: El comportamiento de try_files ante un directorio existente.
Cuando nginx evalúa try_files para la ruta /ai-search:
1. $uri → busca un archivo llamado ai-search → no existe
2. $uri/ → busca un directorio llamado ai-search/ → sí existe
3. Nginx emite un redirect 301 a /ai-search/ (agrega trailing slash)
Hasta aquí el comportamiento es correcto. El problema aparece en el paso 3: por defecto nginx genera redirects absolutos usando el puerto en el que está escuchando. Como nginx escucha en 8080 (requerimiento de Cloud Run), el redirect generado es:
HTTP/1.1 301 Moved Permanently
Location: http://hectorgarrido.cl:8080/ai-search/
El usuario sigue ese redirect y llega a hectorgarrido.cl:8080 — un puerto que no está expuesto al exterior. La página se queda pegada indefinidamente.
¿Por qué Home → /ai-search funciona? Porque la navegación interna usa React Router client-side. React Router hace un history.pushState('/ai-search') — nunca hay una request HTTP a nginx, nunca hay redirect, nginx no tiene oportunidad de interferir.
¿Por qué solo afecta rutas con directorio? Porque / tiene su index.html directamente en la raíz — try_files lo encuentra como archivo en el primer intento ($uri → index.html). No necesita buscar el directorio y no emite redirect.
Fix: Dos Directivas en nginx.conf
server {
listen 8080;
server_name _;
root /usr/share/nginx/html;
index index.html;
# Cloud Run expone el puerto 8080 internamente pero el tráfico público
# llega por 443. Sin estas directivas, nginx genera redirects 301
# exponiendo el puerto interno (ej: http://host:8080/ai-search/).
port_in_redirect off;
absolute_redirect off;
# ...resto de la config
}
port_in_redirect off — suprime el puerto en los redirects generados por nginx. En lugar de http://hectorgarrido.cl:8080/ai-search/, genera http://hectorgarrido.cl/ai-search/.
absolute_redirect off — va más lejos: genera redirects relativos (/ai-search/ en vez de una URL absoluta). Esto es más robusto en cualquier entorno con proxy o load balancer que pueda cambiar el host o protocolo.
Ambas directivas son necesarias. port_in_redirect off sin absolute_redirect off podría seguir generando URLs con el esquema incorrecto (http:// en vez de https://) si el proxy no preserva el header Host.
Esta es una clase de bugs que solo se manifiesta en producción: localmente nginx no está detrás de un Cloud Run proxy, y el puerto 80 coincide con el puerto por defecto, así que los redirects absolutos parecen correctos.
El Error de Deploy: --startup-cpu-boost vs --cpu-boost
No todo salió bien en el primer intento. Al hacer merge a main para desplegar, el pipeline de GitHub Actions falló con:
Error: google-github-actions/deploy-cloudrun failed with: failed to deploy:
ERROR: (gcloud.run.deploy) unrecognized arguments: --startup-cpu-boost
(did you mean '--cpu-boost'?)
La documentación de Google Cloud refiere el flag como --cpu-boost. La acción deploy-cloudrun@v2 pasa los flags directamente a gcloud run deploy, que rechazó el nombre incorrecto. Un commit de corrección (bc41b0b) reparó el flag antes de que el pipeline completara.
Lección: Los flags de gcloud tienen nombres exactos que no siempre coinciden con la documentación de la consola o los nombres intuitivos. Siempre verifica con gcloud run deploy --help antes de asumir.
Tests de Regresión
Los tres fixes se protegieron con tests específicos para evitar regresiones futuras.
Tests de Home.js: Contenido Estático Sin API
// src/pages/Home.test.js
beforeEach(() => {
// Simular un cold start: API no disponible
require('../api/client').default.get.mockRejectedValue(
new Error('Network Error')
);
});
test('renderiza el hero sin esperar la API', () => {
render(<Home />);
expect(screen.getByText('Héctor Garrido Henríquez')).toBeInTheDocument();
});
test('renderiza estadísticas sin esperar la API', () => {
render(<Home />);
expect(screen.getByText(/10\+/)).toBeInTheDocument(); // años de experiencia
});
test('no muestra spinner de página completa', () => {
render(<Home />);
expect(screen.queryByText('Cargando contenido...')).not.toBeInTheDocument();
});
test('muestra spinner solo en el tag cloud', () => {
render(<Home />);
// El spinner existe pero solo en la sección de tags
const spinners = screen.queryAllByRole('progressbar');
expect(spinners.length).toBeLessThanOrEqual(1);
});
Tests de generate-seo.js: Body HTML Inyectado
// src/generateSeo.test.js
test('inyecta body HTML dentro de #root', () => {
const template = '<html><body><div id="root"></div></body></html>';
const result = generatePage(template, { bodyHtml: '<h1>Contenido</h1>' });
expect(result).toContain('<div id="root"><h1>Contenido</h1></div>');
});
test('escapa XSS en body HTML del post', () => {
const post = { title: '<script>alert(1)</script>', excerpt: 'ok', ... };
const bodyHtml = buildPostBodyHtml(post);
expect(bodyHtml).not.toContain('<script>');
expect(bodyHtml).toContain('<script>');
});
test('renderiza nombre del autor en Home body HTML', () => {
const bodyHtml = buildHomeBodyHtml();
expect(bodyHtml).toContain('Héctor Garrido Henríquez');
});
Tests de client.js: Warm-up y Retry
// src/api/client.test.js
test('warm-up URL elimina /api del BASE_URL', () => {
const base = 'https://api.hectorgarrido.cl/api';
const healthUrl = base.replace(/\/api\/?$/, '') + '/healthz';
expect(healthUrl).toBe('https://api.hectorgarrido.cl/healthz');
});
test('reintenta 3 veces en errores 502/503/504', async () => {
// Verifica que el interceptor de retry funciona
// con backoff de 2s → 4s → 8s
});
Cronología de Commits
| Commit | Cambio | Descripción |
|---|---|---|
825fe1f |
Home.js |
Desacopla contenido estático del estado de carga de la API |
825fe1f |
generate-seo.js |
Inyecta body HTML pre-renderizado para todas las rutas |
825fe1f |
deploy.yml |
Agrega --min-instances=1 y --startup-cpu-boost (flag incorrecto) |
825fe1f |
client.js |
Warm-up ping fire-and-forget a /healthz al cargar módulo |
825fe1f |
Tests (3 archivos) | 25+ tests nuevos, totales: 52 frontend + 83 backend |
bc41b0b |
deploy.yml |
Corrige flag a --cpu-boost (nombre correcto de gcloud) |
15a5cb4 |
nginx.conf |
port_in_redirect off + absolute_redirect off para rutas SPA |
Resultado Final
| Aspecto | Antes | Después |
|---|---|---|
| Cold start visible | 15-30 seg de spinner total | Contenido hardcodeado inmediato; solo tag cloud espera |
| Instancias mínimas | 0 (escala a cero) | 1 (siempre activa) |
Body en index.html |
<div id="root"></div> |
Hero + proyectos + competencias pre-renderizados |
| Body en posts | <div id="root"></div> |
Título + fecha + tags + excerpt pre-renderizados |
| Social previews | Tarjeta vacía | Contenido visible sin ejecutar JS |
/ai-search directo |
Redirige a host:8080 (roto) |
Carga correctamente |
| Todas las rutas directas | Redirige a host:8080 (roto) |
Cargan correctamente |
| Tests de regresión | — | 3 archivos nuevos, 25+ tests |
El sistema de warm-up más los --min-instances=1 resuelven el cold start en producción. El body HTML pre-renderizado resuelve el problema de SPA vacío para crawlers y redes sociales. Y los tests garantizan que ningún cambio futuro revierta accidentalmente estos comportamientos.
Lecciones
1. Costo vs. UX en instancias mínimas. --min-instances=0 ahorra dinero pero destruye la primera impresión. Para un portafolio profesional, vale más pagar ~$1/mes que esperar 20 segundos delante de un potencial empleador.
2. Distinguir entre "necesita API" y "depende de API". El tag cloud necesita la API. El hero, estadísticas y proyectos también están relacionados con el contenido de la API conceptualmente — pero los datos específicos que muestran son hardcodeados en el componente. No todo lo que está en una página con llamadas API realmente necesita esperar esas llamadas.
3. Pre-render parcial es mejor que ninguno. React no necesita pre-rendering para funcionar, pero los crawlers y las previews de redes sociales sí se benefician. generate-seo.js no reemplaza a react-snap — hace algo diferente: inyecta HTML estático simplificado que es suficiente para bots, mientras React entrega la experiencia completa a usuarios reales.
4. Verifica flags de gcloud antes del primer deploy. El error --startup-cpu-boost vs --cpu-boost costó un ciclo de deploy innecesario. gcloud run deploy --help habría prevenido esto en 30 segundos.
5. Los bugs que solo aparecen en producción son los más peligrosos. El redirect de nginx exponiendo :8080 era invisible en desarrollo local porque nginx escucha en el puerto 80 — el mismo que usa el browser por defecto. En producción, la diferencia entre el puerto interno (8080) y el externo (443) es invisible para los developers pero fatal para los usuarios que navegan directamente a una URL.
6. generate-seo.js creó un problema que no existía antes. Al generar directorios físicos para el pre-render, el script cambió el comportamiento de try_files: rutas que antes caían al fallback /index.html ahora matchean $uri/ y desencadenan redirects. Cada optimización introduce la posibilidad de nuevas interacciones inesperadas con el resto del stack.
Anterior: Cinco Bugs en Cadena: Una Noche Arreglando el Admin de Django en Producción Siguiente: De GitHub Copilot a Claude Code: Automatizando la Documentación del Proyecto