Tutoriais de VPS
Next.js na VPS: Docker standalone, HTTPS e reversão
Implante Next.js com Docker standalone, Compose e Caddy. Inclua arquivos estáticos, separe variáveis de build/runtime e teste saúde, backups e reversão.

Este deploy parte de um projeto App Router com package-lock.json. Ele cria imagem Node.js standalone, usa Compose e Caddy para HTTPS. Uma máquina pode interromper requisições ao substituir o contêiner; deploy gradual exige instâncias, versões e cache coordenados.
| Necessidade | Abordagem | Motivo |
|---|---|---|
| Páginas estáticas sem servidor | Exportação e servidor web | Evita manter Node.js |
| SSR, Route Handlers, Server Actions, ISR | Contêiner standalone | Precisa do servidor Next.js |
| Vários servidores/atualização gradual | Balanceador e cache/versões coordenados | Compose não sincroniza instâncias |
Para Express, veja Node.js. Aqui tratamos artefatos e execução Next.js.
Use Ubuntu 24.04, Docker/Compose suportados e DNS para app.example.com. 2 vCPU/4 GB/40 GB SSD é referência, não mínimo oficial. next build grande pode exigir 8 GB ou CI. Reserve imagens/logs/versões anteriores; abra 80/443, limite SSH e mantenha 3000 privada.
Confira npm ci e npm run build localmente. O exemplo usa npm; adapte comandos e lockfile de forma coerente para pnpm/Yarn.
Mescle standalone em next.config.ts, sem apagar ajustes:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
output: 'standalone',
}
export default nextConfig
Crie app/api/health/route.ts:
export async function GET() {
return Response.json({ status: 'ok' })
}
Ele verifica resposta web, não banco/filas/API. Monitore dependências separadamente e evite redirects inesperados do middleware de idioma/autenticação. Healthcheck marca unhealthy; restart não reinicia automaticamente só por esse estado.
Crie 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 não inclui automaticamente public nem .next/static; omissões podem deixar página inicial funcionando e arquivos 404. Confira Next.js/dependências nativas com Node 24. Monorepos podem exigir outputFileTracingRoot e caminhos aninhados. Guarde uploads em volume/objetos, com escrita mínima para usuário não root.
Crie .dockerignore:
node_modules
.next
.git
.env*
app.env
*.log
Crie 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:
Ajuste limites de execução por medição; eles não limitam o build. Preserve volumes Caddy. A condição de saúde controla início, não recuperação contínua.
Crie Caddyfile:
{$DOMAIN} {
encode zstd gzip
reverse_proxy app:3000
}
.env interpola Compose; app.env contém variáveis do servidor em execução:
# .env
DOMAIN=app.example.com
APP_VERSION=2026-09-25-a1b2c3d
# app.env:仅示例;替换为你的真实服务端变量
API_BASE_URL=https://api.example.com
Adicione .env e app.env ao .gitignore; aplique chmod 600 .env app.env. O comentário do segundo arquivo indica exemplo: substitua pelo valor real.
Nunca ponha segredos em NEXT_PUBLIC_: são incorporados ao navegador durante next build. Alterar NEXT_PUBLIC_ exige reconstrução. Como .env fica fora do contexto e env_file só atua em execução, forneça valores públicos de build por argumentos/ambiente Docker antes de compilar. Use segredos de build para credenciais privadas, sem camadas persistentes. Variáveis de servidor usadas na pré-renderização também podem ser avaliadas no build.
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 só valida sintaxe. Teste imagem, endpoint, arquivos e certificado. Caddy precisa de A/AAAA corretos e 80/443 acessíveis para o desafio habitual. Se Nginx, painel ou gateway já ocupa as portas, integre com a entrada escolhida.
Use commit/versão em APP_VERSION, sem sobrescrever latest:
docker compose build app
docker compose up -d --no-deps app
docker compose ps
curl -fsS https://app.example.com/api/health
A substituição pode interromper brevemente; confira saúde e páginas reais. Para reverter, altere .env e seu APP_VERSION para imagem anterior preservada e execute docker compose up -d --no-deps app. Confirme existência e use --no-build para não compilar código novo sob tag antiga. Não limpe imagens antes. Reverter código não reverte migração: planeje compatibilidade ou recuperação de dados.
Copie Git, .env/app.env protegidos, banco/uploads/objetos e estado pertinente do gateway. Cache .next não é fonte única de dados duráveis. Preserve cópia externa e teste recuperação isolada. Veja Compose em produção. Várias instâncias precisam de identificadores, chaves Server Actions e cache compatíveis.
| Sintoma | Conferir | Ação |
|---|---|---|
| 502 | docker compose ps, docker compose logs app | Build, saúde e upstream Caddy |
/_next/static/* 404 | /app/.next/static | Corrigir COPY e reconstruir |
Imagem public 404 | /app/public | COPY e maiúsculas/minúsculas Linux |
| Variável ignorada | NEXT_PUBLIC_ | Recompilar cliente; conferir pré-renderização/runtime |
| Build encerrado à força | free -h, dmesg, docker system df | OOM, capacidade/CI; preservar imagens/dados |
| Sem certificado | DNS, portas, firewall e logs | Corrigir registros/listeners e conferir emissão |
Referências: Next.js, Docker standalone, Compose em produção, HTTPS Caddy. Teste build, saúde, arquivos e reversão no domínio real antes de publicar.