De GitHub a producción: despliega Next.js, PostgreSQL y un dominio personalizado

Llevar una aplicación Next.js desde tu ordenador hasta producción suele reducirse a cinco pasos: el script de arranque, la conexión a la base de datos, las variables de entorno (distinguiendo las de compilación de las de ejecución), las migraciones de tablas y el dominio con HTTPS.

En esta guía tomamos un repositorio existente de Next.js y lo desplegamos junto con PostgreSQL en tu propio servidor. Antes de empezar, conecta un servidor Linux a Zenavo.

1. Revisa el package.json de tu repositorio

Si el repositorio no tiene un Dockerfile propio, Zenavo usa zbpack para detectar y compilar Next.js automáticamente. Asegúrate de haber subido el archivo de bloqueo (package-lock.json, pnpm-lock.yaml, yarn.lock o bun.lockb) y de que package.json incluye los scripts estándar de producción:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "engines": {
    "node": ">=20"
  }
}

Ejecuta npm run build en local una vez antes de desplegar para detectar a tiempo errores de tipos de TypeScript o fallos durante la compilación.

2. Despliega PostgreSQL

Crea un proyecto en Zenavo, elige el servidor, haz clic en Añadir servicio → Base de datos → PostgreSQL, selecciona la versión y despliega.

La base de datos corre en la red privada del proyecto y no expone su puerto a internet por defecto. En cuanto está lista, comparte sus variables de conexión con el resto de servicios del proyecto; cuando el servicio se llama postgresql, la variable con la cadena de conexión completa es POSTGRESQL_CONNECTION_STRING.

3. Añade la aplicación Next.js desde GitHub

En el mismo proyecto, haz clic en Añadir servicio → GitHub, autoriza a la GitHub App de Zenavo a leer tu repositorio y elige el repositorio, la rama y el directorio raíz (si es un monorepo y la web está en apps/web, pon apps/web como directorio raíz).

En las variables de entorno, haz referencia a la base de datos:

DATABASE_URL=${POSTGRESQL_CONNECTION_STRING}

${POSTGRESQL_CONNECTION_STRING} es una referencia entre servicios de Zenavo que en tiempo de ejecución se sustituye por la cadena de conexión interna real (si le pusiste otro nombre al servicio de base de datos, usa el nombre de variable que muestra la consola).

Por defecto, next start toma automáticamente la variable PORT que le pasa la plataforma. Si usas tu propio Dockerfile o un server.js personalizado, asegúrate de que escuche en 0.0.0.0 y en el mismo puerto HTTP configurado en el servicio de Zenavo. Tienes más detalles en la guía de Next.js.

4. Diferencia entre NEXT_PUBLIC_* y las variables de servidor

Next.js trata estos dos tipos de variables de entorno de forma muy distinta:

• Variables de servidor (como DATABASE_URL, claves de pasarelas de pago o API keys de IA): solo se leen en código de servidor y nunca deben llevar el prefijo NEXT_PUBLIC_. Cuando las cambias en la pestaña Variable de Zenavo, basta con reiniciar el servicio para aplicar el nuevo valor.
• Variables NEXT_PUBLIC_*: se incrustan directamente en el paquete JavaScript del navegador durante next build. Si cambias una variable NEXT_PUBLIC_*, tienes que volver a desplegar (recompilar); reiniciar el contenedor no cambia el valor que ya quedó empaquetado.

Además, las máquinas de compilación de Zenavo no tienen acceso a la base de datos privada de tu servidor durante next build. Por tanto:

• No ejecutes migraciones de la base de datos de producción dentro del script build;
• Las páginas que consulten la base de datos deben usar renderizado dinámico en cada petición en lugar de pregenerarse estáticamente durante la compilación.

5. Ejecuta las migraciones al arrancar (ejemplo con Prisma)

Como durante la compilación no se puede conectar a la base de datos interna, las migraciones de esquema deben ejecutarse justo antes de arrancar el contenedor, no en build.

Si compilas con zbpack, puedes añadir un script predeploy en package.json, que se ejecuta automáticamente antes de start en cada despliegue:

{
  "scripts": {
    "build": "prisma generate && next build",
    "predeploy": "prisma migrate deploy",
    "start": "next start"
  }
}

Dos detalles importantes:

• En producción usa siempre prisma migrate deploy (que aplica las migraciones subidas al repositorio), nunca prisma migrate dev ni db push --force-reset.
• Si usas tu propio Dockerfile, el gancho predeploy de zbpack no interviene: pon npx prisma migrate deploy && npm start en el CMD o ENTRYPOINT de tu Dockerfile.

6. Asocia un dominio y activa el despliegue automático

Cuando arranque la aplicación, entra en la pestaña Red del servicio, asocia tu dominio (como app.example.com), apunta un registro A de DNS a la IP del servidor y espera a que se emita automáticamente el certificado HTTPS (ver Dominios y HTTPS). Si usas NextAuth / Auth.js, Clerk u OAuth, acuérdate de actualizar también NEXTAUTH_URL y las URL de callback en los paneles de terceros.

Abre la web, inicia sesión y prueba a crear, leer, editar y borrar un registro para confirmar que la aplicación lee y escribe en PostgreSQL.

En los Ajustes del servicio, activa Desplegar automáticamente al hacer push a esta rama para que cada git push compile y despliegue sin corte de servicio. En un monorepo puedes configurar rutas vigiladas para que solo se despliegue cuando cambie esa carpeta (ver Desplegar desde GitHub).

Preguntas frecuentes

¿El registro de compilación falla con Can't reach database server at postgresql.zenavo.internal:5432? Tu script build o alguna página generada estáticamente (SSG) está intentando conectarse a la base de datos interna durante la compilación. Pasa las migraciones a predeploy (o al comando de arranque) y añade export const dynamic = 'force-dynamic' a las páginas que consulten la base de datos.

¿He cambiado NEXT_PUBLIC_API_URL y reiniciado, pero la web sigue usando la dirección antigua? Las variables NEXT_PUBLIC_* se incrustan al compilar. Haz clic en Volver a desplegar (Redeploy) para lanzar una compilación nueva.

¿Cómo vuelvo atrás si un despliegue nuevo tiene un fallo? Desde el historial de despliegues puedes revertir la aplicación a la imagen anterior con un clic. Ten en cuenta que revertir el servicio restaura la imagen y las variables de la aplicación, pero no la base de datos. Antes de aplicar migraciones destructivas (como borrar una columna), haz una copia de seguridad en la pestaña Copias de seguridad y restauración del servicio PostgreSQL.

Cuando tengas listo el repositorio, crea un proyecto en la consola de Zenavo: levanta PostgreSQL, conecta tu repositorio de GitHub, configura DATABASE_URL y asocia tu dominio para pasar de git push a producción en pocos minutos.