Tutoriales de VPS
Next.js en un VPS: Docker standalone, HTTPS y reversión
Despliega Next.js con Docker standalone, Compose y Caddy. Incluye recursos estáticos, separa variables de build/runtime y verifica salud, copias y reversión.

Este despliegue parte de un proyecto App Router con package-lock.json. Construye imagen Node.js standalone, usa Compose y Caddy para HTTPS. Una sola máquina puede interrumpir solicitudes al reemplazar el contenedor; despliegue gradual exige instancias, versiones y caché coordinadas.
| Necesidad | Enfoque | Motivo |
|---|---|---|
| Páginas estáticas sin servidor | Exportación y servidor web | Evita mantener Node.js |
| SSR, Route Handlers, Server Actions, ISR | Contenedor standalone | Necesita servidor Next.js |
| Varios servidores/actualización gradual | Balanceador y caché/versiones coordinadas | Compose no sincroniza instancias |
Para Express consulta Node.js. Aquí tratamos artefactos y ejecución Next.js.
Usa Ubuntu 24.04, Docker/Compose soportados y DNS para app.example.com. 2 vCPU/4 GB/40 GB SSD es referencia, no mínimo oficial. next build grande puede necesitar 8 GB o CI. Reserva imágenes/logs/versiones anteriores; abre 80/443, limita SSH y deja 3000 privado.
Verifica npm ci y npm run build localmente. El ejemplo usa npm; adapta comandos y lockfile coherentemente para pnpm/Yarn.
Combina standalone con next.config.ts, sin borrar ajustes:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
output: 'standalone',
}
export default nextConfig
Crea app/api/health/route.ts:
export async function GET() {
return Response.json({ status: 'ok' })
}
Comprueba respuesta web, sin verificar base/colas/API. Monitoriza dependencias aparte y evita redirects inesperados del middleware de idioma/autenticación. Un healthcheck marca unhealthy; restart no reinicia automáticamente solo por ese estado.
Crea Dockerfile:
FROM node:24-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund
FROM node:24-bookworm-slim AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN mkdir -p public && npm run build
FROM node:24-bookworm-slim AS runner
WORKDIR /app
ENV NODE_ENV=production PORT=3000 HOSTNAME=0.0.0.0
RUN mkdir -p .next && chown node:node .next
COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
USER node
EXPOSE 3000
CMD ["node", "server.js"]
Standalone no incluye automáticamente public ni .next/static; omitirlos puede dejar portada funcional y recursos 404. Verifica Next.js/dependencias nativas con Node 24. Monorepos pueden necesitar outputFileTracingRoot y rutas anidadas. Guarda uploads en volumen/objetos, con escritura mínima para el usuario no root.
Crea .dockerignore:
node_modules
.next
.git
.env*
app.env
*.log
Crea compose.yaml:
services:
app:
image: nextjs-app:${APP_VERSION}
build: .
init: true
restart: unless-stopped
env_file:
- ./app.env
environment:
NODE_ENV: production
HOSTNAME: 0.0.0.0
PORT: '3000'
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://127.0.0.1:3000/api/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
mem_limit: 1g
cpus: '1.5'
pids_limit: 256
security_opt:
- no-new-privileges:true
caddy:
image: caddy:2
restart: unless-stopped
depends_on:
app:
condition: service_healthy
environment:
DOMAIN: ${DOMAIN}
ports:
- '80:80'
- '443:443'
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
Ajusta límites de ejecución mediante medición; no limitan el build. Conserva volúmenes Caddy. La condición de salud controla inicio, no recuperación continua.
Crea Caddyfile:
{$DOMAIN} {
encode zstd gzip
reverse_proxy app:3000
}
.env interpola Compose; app.env contiene variables del servidor en ejecución:
# .env
DOMAIN=app.example.com
APP_VERSION=2026-09-25-a1b2c3d
# app.env:仅示例;替换为你的真实服务端变量
API_BASE_URL=https://api.example.com
Añade .env y app.env a .gitignore; aplica chmod 600 .env app.env. El comentario del segundo archivo señala un ejemplo: sustituye el valor real.
Nunca pongas secretos en NEXT_PUBLIC_: se incorporan al navegador durante next build. Cambiar NEXT_PUBLIC_ requiere reconstruir. Como .env queda fuera del contexto y env_file solo actúa en ejecución, proporciona variables públicas de build mediante argumentos/entorno Docker antes de compilar. Usa secretos de build para credenciales privadas, sin capas persistentes. Variables de servidor usadas al prerenderizar también pueden quedar fijadas al construir.
docker compose config --quiet
docker compose build app
docker compose up -d
docker compose ps
docker compose logs --tail=100 app caddy
curl -I https://app.example.com/
docker compose config --quiet solo valida sintaxis. Prueba imagen, endpoint, recursos y certificado. Caddy requiere A/AAAA correctos y 80/443 accesibles para su validación habitual. Si Nginx, panel u otro gateway ya usa esos puertos, integra con la entrada elegida.
Usa commit/versión en APP_VERSION, sin sobrescribir latest:
docker compose build app
docker compose up -d --no-deps app
docker compose ps
curl -fsS https://app.example.com/api/health
El reemplazo puede interrumpir brevemente; verifica salud y páginas reales. Para volver, cambia .env y su APP_VERSION a imagen anterior conservada y ejecuta docker compose up -d --no-deps app. Confirma existencia y usa --no-build para evitar construir código nuevo con etiqueta antigua. No limpies imágenes antes. Revertir código no revierte migración: diseña compatibilidad o recuperación de datos.
Copia Git, .env/app.env protegidos, base/uploads/objetos y estado de gateway pertinente. Caché .next no es fuente única de datos duraderos. Conserva copia externa y prueba recuperación aislada. Consulta Compose productivo. Varias instancias necesitan identificadores, claves Server Actions y caché compatibles.
| Síntoma | Comprobar | Acción |
|---|---|---|
| 502 | docker compose ps, docker compose logs app | Build, salud y upstream Caddy |
/_next/static/* 404 | /app/.next/static | Corregir COPY y reconstruir |
Imagen public 404 | /app/public | COPY y mayúsculas/minúsculas Linux |
| Variable ignorada | NEXT_PUBLIC_ | Recompilar cliente; revisar prerender/runtime |
| Build terminado a la fuerza | free -h, dmesg, docker system df | OOM, capacidad/CI; preservar imágenes/datos |
| Sin certificado | DNS, puertos, firewall y logs | Corregir registros/listeners y revisar emisión |
Referencias: Next.js, Docker standalone, Compose productivo, HTTPS Caddy. Prueba build, salud, recursos y reversión con dominio real antes de publicar.