Docker Next.js producción: Guía completa de despliegue

¿Por qué usar Docker para desplegar Next.js?

Docker es una plataforma de contenedorización que nos permite empaquetar una aplicación con todas sus dependencias lógicas, librerías del sistema operativo y configuraciones en una única imagen ejecutable y ligera. Al desplegar Next.js en contenedores, eliminamos por completo el clásico problema técnico de "en mi máquina local sí funcionaba", garantizando que el software corra en cualquier servidor de la nube.

Adicionalmente, Docker optimiza el uso de recursos lógicos en servidores VPS en comparación con el uso de máquinas virtuales tradicionales. Al compartir el núcleo del sistema operativo anfitrión, podemos correr múltiples contenedores aislados de forma ligera, facilitando el escalado horizontal y permitiendo automatizar el despliegue mediante tuberías de CI/CD (Integración y Despliegue Continuo) sin fricción técnica.

Crear el Dockerfile optimizado de producción multietapa

Un Dockerfile básico para Next.js que simplemente copie todo el directorio e instale las dependencias lógicas generará imágenes de producción gigantes de hasta 1 GB de peso, retrasando innecesariamente la descarga en el servidor. Para resolver esto, utilizaremos la técnica de construcción multietapa (multi-stage build), dividiendo el proceso en tres fases distintas.

La primera fase instala las dependencias; la segunda compila la aplicación Next.js produciendo la versión optimizada para producción; y la tercera etapa copia únicamente los binarios compilados y la carpeta .next/standalone a una imagen base mínima de Node.js alpina de bajo peso. Esto da como resultado una imagen docker final de producción menor a los 100 MB, acelerando la velocidad de despliegue de forma notable.

Configurar Docker Compose para desarrollo local

Mientras que el Dockerfile define la imagen de producción, utilizar Docker Compose es la mejor vía para coordinar múltiples contenedores localmente en desarrollo (como la base de datos, el backend y el frontend) de forma unificada. Al declarar el ecosistema completo en un archivo docker-compose.yml, el equipo puede levantar todo el sistema con un solo comando.

Configuraremos volúmenes en caliente para enlazar el código local de la computadora con el interior del contenedor, de modo que cualquier modificación en los archivos de TypeScript de Next.js se refleje de forma inmediata en el navegador mediante Hot Reload, sin necesidad de compilar la imagen del contenedor nuevamente tras cada modificación lógica.

Manejo seguro de variables de entorno en producción

Next.js maneja variables de entorno de dos formas: en tiempo de compilación (aquellas con el prefijo NEXT_PUBLIC_ que se inyectan directamente en el cliente en los archivos de JavaScript) y en tiempo de ejecución (aquellas leídas únicamente por el servidor en las APIs). Manejar esto en Docker requiere precaución técnica.

Dado que las variables del cliente se graban físicamente en el build estático de Next.js, deben estar disponibles durante la fase de construcción de la imagen de Docker, por lo que utilizaremos la directiva ARG en el Dockerfile. Por otro lado, las variables privadas del servidor pueden inyectarse dinámicamente en tiempo de ejecución al inicializar el contenedor mediante archivos .env seguros en la infraestructura.

Nginx como reverse proxy e integración de certificados HTTPS

Aunque el contenedor standalone de Next.js puede escuchar peticiones web directamente, en arquitecturas profesionales de producción se prefiere colocar un servidor Nginx al frente actuando como Reverse Proxy. Nginx intercepta las peticiones entrantes en los puertos estándar 80 y 443, distribuye el tráfico y maneja la compresión de archivos de forma eficiente.

Además, Nginx se encarga de gestionar de forma robusta la encriptación de tráfico de datos mediante certificados de seguridad SSL/TLS gratuitos de Let's Encrypt, redirigiendo de forma estricta todo el tráfico HTTP no seguro a HTTPS de forma automática, cumpliendo con los estándares de seguridad perimetral obligatorios exigidos en la web moderna.

Despliegue paso a paso en un servidor VPS remoto

Para desplegar la aplicación dockerizada en tu propio servidor VPS (como un droplet de DigitalOcean o una instancia de AWS EC2), debes instalar previamente Docker y Docker Compose en la consola del servidor remoto. A continuación, transfiere el código estructurado o configura un repositorio Git para clonar el proyecto.

Una vez descargado el código, configura el archivo de variables de entorno en producción. Ejecuta el comando de construcción en segundo plano. El sistema descargará las imágenes base necesarias, ejecutará las fases multietapa de compilación de Next.js y levantará el servidor de forma aislada, permitiéndote actualizar el sitio sin caídas de servicio.

Código completo del Dockerfile y Compose

A continuación se presentan los archivos de configuración listos para producción:

Dockerfile Multietapa (Dockerfile):

# Etapa 1: Dependencias
FROM node:18-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Etapa 2: Compilacion
FROM node:18-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# Soportar inyeccion de variables de cliente
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
ENV NEXT_TELEMETRY_DISABLED 1
RUN npm run build

# Etapa 3: Produccion
FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV production
ENV PORT 3000
ENV HOSTNAME "0.0.0.0"
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# Copiamos unicamente lo necesario
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]
  

Docker Compose (docker-compose.yml):

version: '3.8'

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - NEXT_PUBLIC_API_URL=https://api.teamsoftcode.com
    ports:
      - "3000:3000"
    restart: always
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/db
  

El uso de la propiedad standalone en Next.js (configurada en next.config.js con la opción output: 'standalone') compila un servidor de node mínimo que no requiere de la carpeta `node_modules` gigante original en el contenedor final.

Errores comunes y cómo solucionarlos

El error más clásico es obtener una página web en blanco en el navegador debido a que la variable de entorno NEXT_PUBLIC_API_URL no se inyectó en tiempo de build de Docker, provocando que las llamadas de API apunten a undefined. Recuerda que las variables con prefijo público deben declararse obligatoriamente como args en la fase de construcción en el comando docker-compose, de lo contrario no se grabarán en el estático de React.

Otro problema recurrente es el fallo de permisos del sistema de archivos al arrancar el contenedor: "Error: EACCES: permission denied". Esto ocurre cuando la imagen standalone intenta escribir en directorios internos como la caché sin contar con los privilegios adecuados. Asegúrate de configurar correctamente la propiedad de propiedad de usuario (chown nextjs:nodejs) en el Dockerfile para el usuario no administrativo del sistema.

Conclusión

Dockerizar tu servidor Next.js garantiza despliegues predecibles, rápidos y altamente seguros en cualquier infraestructura en la nube. Si requieres asistencia experta o una consultoría técnica para optimizar los flujos de despliegue de tu equipo, no dudes en ponerte en contacto conmigo.

¿Necesitas implementar esto en un proyecto real? Revisa mis servicios de desarrollo o contáctame directamente.