Alojar o Next.js no seu próprio servidor com publicação a cada git push

O caminho curto para alojar o Next.js no seu próprio servidor é instalar um painel de publicação como o Coolify e ligar o seu repositório do GitHub. Depois disso, cada git push compila a aplicação e põe a nova versão no ar por HTTPS. Segundo a documentação do Next.js, todas as funcionalidades funcionam quando publica com um servidor Node.js ou um contentor Docker, por isso não fica preso a nenhuma plataforma especial.

Que funcionalidades funcionam no seu próprio servidor?

A tabela da documentação oficial é curta: um servidor Node.js e o Docker suportam todas as funcionalidades, e a exportação estática é limitada. Num único servidor, isto significa, na prática:

• Os server components, as rotas de API e as respostas em streaming funcionam com next start.
• O next/image não precisa de configuração extra, e as imagens são processadas no servidor.
• A cache e a regeneração estática incremental (ISR) funcionam por si num único servidor com disco persistente. Se executar várias cópias, tem de partilhar a cache entre elas.
• A recomendação oficial é pôr um proxy inverso à frente, em vez de expor o Next.js diretamente. O Coolify traz o Traefik para isso, e o Traefik também obtém o certificado.

Que capacidade deve ter o servidor?

É a compilação que decide quanta memória precisa, e não a aplicação em execução. O next build tem um pico, e a aplicação precisa de muito menos depois de estar no ar. O próprio Coolify também usa memória. Estes são os valores que medimos em servidores reais:

O projeto pequeno era a aplicação Next.js de exemplo do Coolify. O maior era uma aplicação de conversa com IA escrita em Next.js 16 e cerca de 85 pacotes, que ficou sem memória com 2 GB durante a verificação do TypeScript. O servidor tinha 2 GB de swap, e os valores mostram o ponto mais alto. A utilização de disco depois da primeira compilação foi de 13 a 18 GB. São medições nossas, e o seu projeto será diferente. Se uma compilação falhar por falta de memória, aumente primeiro e, mais tarde, volte a reduzir se puder.

Passo a passo

1. Ligue o repositório

Inicie sessão no Coolify, abra o seu projeto na página Projects e prima New resource. Para um repositório público, escolha Public Git Repository, introduza o endereço e prima Check repository.

2. Adicione uma chave se o repositório for privado

No menu da esquerda, vá a Private Keys, em Keys & Tokens, e crie uma chave com Generate ED25519. Adicione a chave pública em Deploy keys, na página Settings do repositório no GitHub. Depois use New resource, escolha Private Git Repository (with Deploy Key) e introduza [email protected]:user/project.git. Deixe o Build pack em Railpack, que reconhece o Next.js, e a porta fica em 3000. O Coolify marca o Railpack como beta, por isso escolha o seu próprio Dockerfile se tiver problemas.

3. Introduza as variáveis de ambiente

Na página Environment Variables, mude para Developer view e cole o conteúdo do seu ficheiro .env. Há um pormenor que importa: as variáveis cujo nome começa por NEXT_PUBLIC_ são escritas no código durante a compilação. Quando alterar uma, prima Redeploy: o painel vê que uma definição de compilação mudou e compila outra vez. Nunca dê esse prefixo a uma chave que o navegador não deva ver.

4. Ligue o seu domínio

Crie um registo A no seu fornecedor de domínio que aponte para o endereço IP do servidor. No Coolify, vá à página Domains, prima Add domain, escolha https como protocolo, introduza o seu domínio, guarde e publique de novo. O certificado é pedido e renovado automaticamente. As portas 80 e 443 têm de estar abertas.

5. Publique

Prima Deploy. A página Deployments mostra o registo da compilação em direto. Quando a compilação termina, o contentor antigo continua a servir até o novo estar pronto.

Como é que um git push se transforma numa publicação?

A cada push, o GitHub envia ao painel um pedido assinado. O painel verifica a assinatura e recompila a aplicação para esse ramo, e um pedido com assinatura inválida é rejeitado. Eis como o configura:

1. Na página Webhooks da aplicação, copie o Webhook URL da secção do GitHub, introduza em Webhook secret um valor aleatório com pelo menos 16 caracteres e guarde.
2. No GitHub, abra Settings do repositório, vá a Webhooks e prima Add webhook.
3. Ponha o endereço em Payload URL e o mesmo valor em Secret. Defina Content type como application/json e deixe o push como único evento.

Para experimentar:

git commit --allow-empty -m "deploy test"

git push

A nova compilação aparece na página Deployments. No pequeno projeto de exemplo, um novo commit entrou no ar em 41 segundos graças à cache de compilação. O GitHub tem de conseguir chegar ao endereço do painel, e como o painel é instalado com um endereço HTTPS público, não é preciso mais nada.

Erros comuns

Com a opção Next.js da Seturack, o Coolify chega instalado: o servidor local está validado, o assistente de boas-vindas já foi tratado e o painel abre por HTTPS. O endereço e a palavra-passe aparecem no seu painel, e começa por ligar o GitHub. Tem acesso root, e pode gerir tudo a partir do painel se preferir. As cópias de segurança diárias estão incluídas no preço e o tráfego é ilimitado. Define o tamanho com controlos deslizantes na página do VPS Next.js.

Pronto a usar na Seturack: Next.js, Coolify.