Dockerizar Next.js: Los desafíos ocultos

Tenía un mes queriendo escribir este artículo. Hay una gran diferencia entre un proyecto pequeño en Vercel y una aplicación real en producción. En Vercel, todo es fácil y se siente color de rosa porque la complejidad está oculta.

Cuando tu proyecto crece, necesitas más control. Pasas de una configuración simple a una infraestructura grande con múltiples pods y reglas de escalado. Yo uso Google Cloud para mis proyectos, pero estos retos son los mismos si usas AWS o Azure.

Este cambio representa una gran transformación en la arquitectura. En Vercel, la plataforma gestiona el sistema por ti. Fuera de Vercel, tú eres el arquitecto. En este artículo, quiero compartir el primer tropiezo que tuve al dockerizar Next.js. Nunca pensé que me daría problemas, pero así fue: las variables de entorno.

Arquitectura en Vercel vs. Arquitectura autogestionada

Cuando usas Vercel, la plataforma te da una "caja negra" que maneja tu compilación, tu despliegue, tu SSL y tu CDN. Cuando pasas a tu propia infraestructura (como Docker en GCP), necesitas reemplazar cada pieza de esa caja.

graph TD
    subgraph "The Vercel Way (Managed)"
        A[Git Push] --> B[Vercel Build Engine]
        B --> C[Vercel Edge Network]
        C --> D[User]
    end
 
    subgraph "The Self-Managed Way (Docker)"
        E[Git Push] --> F[CI/CD Pipeline\nGitHub Actions/GitLab]
        F -->|Build Image| G[Container Registry\nArtifact Registry/ECR]
        G -->|Deploy| H[Cloud Hosting\nCloud Run/App Runner]
        I[Secret Manager] -.->|Runtime Secrets| H
        H --> J[Load Balancer / CDN]
        J --> K[User]
    end

Para que esta arquitectura funcione, la parte más crítica es el pipeline de compilación (Build Pipeline). Aquí es donde tu código se convierte en una imagen de Docker, y es justo donde la mayoría de los desarrolladores se topan con su primer gran problema: las variables de entorno.

El muro técnico: Variables de entorno

Antes de armar nuestra arquitectura, debemos entender cómo maneja Next.js las variables de entorno. Las separa en dos grupos distintos: variables en tiempo de compilación (Build-Time Variables) y variables en tiempo de ejecución (Runtime Variables). En Vercel, esta conexión es transparente: agregas tus variables en el panel y funcionan en ambos casos. En tu propia arquitectura, debes manejar esto manualmente en tu Dockerfile y en tu CI/CD.

Variables en tiempo de compilación (NEXT_PUBLIC_)

Las variables que comienzan con NEXT_PUBLIC_ quedan incrustadas en el bundle final de JavaScript cuando ejecutas npm run build. Son visibles para el navegador.

Ejemplo: URLs de APIs o IDs de analíticas.

Si olvidas agregar estas variables durante el paso de compilación, el archivo JavaScript final tendrá valores undefined o cadenas vacías. Esto ocurre incluso si intentas agregarlas más tarde al iniciar la aplicación.

Variables en tiempo de ejecución (privadas)

Las variables sin este prefijo son privadas y existen únicamente en el servidor. No se empaquetan durante la compilación; en su lugar, se accede a ellas en el momento de procesar cada petición.

Ejemplo: URLs de bases de datos, tokens de APIs o claves de pago.

El escenario

Imagina una aplicación que necesita consultar datos de una API externa. En desarrollo local, todo funciona sin esfuerzo. Creas un archivo .env.local y Next.js toma los valores de forma automática:

# .env.local
NEXT_PUBLIC_API_URL=https://dummyjson.com/products
API_SECRET_KEY=my-super-secret-key-123

• NEXT_PUBLIC_API_URL: Es para el frontend. Le indica a tu aplicación desde dónde consultar la información.
• API_SECRET_KEY: Es una clave privada para la lógica de tu backend.

Cuando ejecutas npm run dev, Next.js lee estas variables y tu aplicación funciona perfectamente. En tu código, accedes a ellas de esta forma:

// Frontend: Esto formará parte del bundle de JS
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
 
// Backend: Esto se quedará únicamente en el servidor
const secret = process.env.API_SECRET_KEY;

Esta "magia" sucede porque Next.js está diseñado para hacer sencillo el desarrollo local. Pero tan pronto como pasas a Docker, esta magia desaparece.

Pasar a Docker

Después de probar la aplicación en local, podrías pensar que pasar a Docker es simple. Si npm run dev y npm run build funcionan en tu máquina, la imagen de Docker también debería funcionar.

Creé mi primer Dockerfile de esta forma:

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build # ❌ ¡Faltan las variables NEXT_PUBLIC_!
CMD ["npm", "start"]

Construí la imagen, inicié el contenedor y encontré mi primer tropiezo. La aplicación estaba corriendo, pero las variables del frontend no estaban. Esto pasa porque Next.js necesita las variables NEXT_PUBLIC_ durante el proceso de compilación. En mi Dockerfile simple, el comando npm run build no tenía acceso a estas variables.

¿El resultado? Los archivos compilados se crearon con valores undefined.

La solución: ARG y ENV

Para solucionar esto, necesitamos pasar estas variables durante la fase de compilación usando ARG y ENV de Docker.

• ARG (Build Argument): Es una variable temporal que se usa únicamente mientras se construye la imagen.
• ENV (Environment Variable): Es una variable permanente dentro del contenedor.

Esta es la forma correcta de escribir el Dockerfile:

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci
 
# 1. Capturar los argumentos en tiempo de compilación
ARG NEXT_PUBLIC_API_URL
# 2. Asignar a ENV para el proceso de compilación
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
 
RUN npm run build
CMD ["npm", "start"]

Ahora puedes construir la imagen con los valores correctos:

docker build --build-arg NEXT_PUBLIC_API_URL="https://api.com" -t my-app .

¿Qué pasa con las variables privadas?

Las variables privadas (sin el prefijo NEXT_PUBLIC_) son diferentes. Nunca debes ponerlas en el Dockerfile. Estas variables se usan cuando el servidor está corriendo, no cuando construyes la imagen.

Puedes inyectarlas al momento de iniciar el contenedor:

docker run -e API_SECRET_KEY="my-secret" my-app

Consideraciones de seguridad

Cuando llevas tu aplicación a un entorno de producción, la seguridad es muy importante. En Vercel, agregas tus secretos en el panel y se encriptan de forma automática.

En tu propia infraestructura, podrías pensar en usar el flag -e API_SECRET_KEY=... al iniciar Docker. Esta no es una buena idea para un proyecto real. No es seguro ni escalable. Escribir tus contraseñas en texto plano en la terminal es un riesgo grande.

En su lugar, deberías usar un Secret Manager. Los grandes proveedores cloud como Google Cloud, AWS y Azure ofrecen servicios para gestionar tus secretos de forma segura.

Cuando tu contenedor arranca, el proveedor cloud inyecta estos secretos directamente en el entorno. Esta es una forma de trabajar mucho mejor, ya que tus secretos nunca quedan guardados en los logs de tu CI/CD, en el historial de la terminal ni en las capas de tu imagen de Docker. Esto mantiene tu aplicación protegida a medida que escala a múltiples pods y configuraciones complejas.

Resumen

Ahora que nuestra imagen de Docker está lista, podemos desplegarla en plataformas serverless modernas como Google Cloud Run. Si quieres un recorrido completo sobre precios, dominios personalizados y configuración de Cloud Build, revisa mi guía paso a paso sobre cómo migrar de Vercel a Google Cloud Run.

En un entorno de producción real, podrías usar una configuración más compleja con muchos pods y Kubernetes. Quise enfocarme en este primer tropiezo porque es la razón más común por la que fallan los despliegues de Next.js.

¿Listo para el siguiente paso? Lee mi guía sobre Next.js en Google Cloud Run: caché de producción, secretos y cero arranques en frío para manejar la gestión de secretos y edge caching.

Espero que esta guía te sea útil cuando migres tu aplicación desde Vercel hacia un entorno cloud real.

¡Happy coding!

Foto de Travis Fish en Unsplash