Deploy de Aplicações Next.js e Nuxt.js SSR no Locaweb Cloud

Trataremos desde a preparação de rede na plataforma Apache CloudStack até os métodos modernos de deploy via Docker e GitHub Actions (CI/CD), além do modelo tradicional com PM2, proxy reverso com Nginx e certificado SSL gratuito via Let’s Encrypt.

1. Pré-requisitos

Para garantir a eficiência total e que a sua operação não sofra interrupções, certifique-se de validar os seguintes requisitos antes de iniciar:

• Conta Locaweb Cloud ativa: Acesso completo ao painel administrativo CloudStack.
• Máquina Virtual (VM): Uma instância ativa com o sistema operacional Ubuntu 22.04 LTS ou superior.
• Chave SSH configurada: Par de chaves cadastrado e associado à sua VM para acesso seguro via terminal. O arquivo da chave privada (extensão .key ou .pem) deve estar salvo na sua máquina local.
• Rede e IP Público: Uma rede (VPC ou Rede Isolada) configurada com um IP Público alocado.
• Domínio próprio: Um domínio de site registrado com permissão para alterar as configurações de apontamento.

 

Está com dúvidas sobre como começar no Locaweb Cloud? Acesse nosso tutorial de apoio. 

2. Configuração de infraestrutura (painel)

Antes de abrir o terminal, precisamos preparar a camada de rede diretamente no painel da Locaweb. O CloudStack isola suas instâncias por padrão para proteger seu ecossistema. Portanto, nenhum tráfego externo alcançará a VM se o encaminhamento de portas (Port Forwarding) e o Firewall não forem configurados primeiro.

2.1. Localizando o IP Público

1. No menu lateral esquerdo do painel, navegue até Rede > Endereços IP públicos.
2. Selecione o link correspondente ao número do seu IP Público alocado à VM.
3. Anote esse endereço: ele será a base para as conexões SSH e para o apontamento do seu domínio.

2.2. Configurando o encaminhamento de portas (Port Forwarding)

Ainda nos detalhes do seu IP Público, acesse a aba Encaminhamento de porta (Port Forwarding) e crie as regras que mapeiam uma porta pública para a porta privada correspondente na VM:

Regra	Protocolo	Porta Pública	Porta Privada	Destino
SSH	TCP	22	22	Sua VM
HTTP	TCP	80	80	Sua VM
HTTPS	TCP	443	443	Sua VM
Aplicação SSR	TCP	3000	3000	Sua VM

 

 

2.3. Configurando as regras de Firewall

Acesse a aba Firewall no painel do seu IP Público e autorize a entrada do tráfego adicionando as seguintes regras de entrada (inbound):

Regra	CIDR de Origem	Protocolo	Porta Inicial	Porta Final	Finalidade
SSH	<SEU_IP_ADMIN>/32	TCP	22	22	Acesso administrativo restrito
HTTP	0.0.0.0/0	TCP	80	80	Acesso público HTTP
HTTPS	0.0.0.0/0	TCP	443	443	Acesso público HTTPS
Aplicação SSR	0.0.0.0/0	TCP	3000	3000	Validação direta (temporária)

 

2.4. Apontamento de DNS do Domínio

No painel do provedor onde o seu domínio está registrado (seja no Registro de Domínio da Locaweb ou entidades externas):

1. Crie um registro do tipo A.
2. No campo Host ou Nome, informe o subdomínio desejado (ex.: app).
3. No campo Aponta para ou Valor, cole o IP Público alocado à sua VM no Locaweb Cloud.

3. Configuração de sistema (Terminal)

Com a infraestrutura de rede liberada no painel administrativo, acesse o terminal do servidor para preparar o ambiente operacional.

3.1. Acesso via SSH

Garanta as permissões restritas ao arquivo da sua chave privada antes de conectar, evitando que o cliente SSH recuse o acesso por segurança:

Bash

# Restringe a leitura e escrita da chave apenas ao seu usuário

chmod 400 ~/caminho/sua-chave.key


# Conecta à VM informando a chave, o usuário padrão 'ubuntu' e 
o IP público

ssh -i ~/caminho/sua-chave.key ubuntu@<SEU_IP_PUBLICO>

Após o login, sincronize os índices de pacotes e aplique as atualizações pendentes para garantir a estabilidade do sistema:

Bash

sudo apt update && sudo apt upgrade -y

3.2. Instalação do Docker e Docker Compose

Para trabalhar com a conteinerização (método altamente recomendado para manter a fluidez do ambiente), execute a instalação a partir do repositório oficial:

Bash

# Instala as dependências necessárias para comunicação via HTTPS

sudo apt-get update

sudo apt-get install -y ca-certificates curl gnupg


# Cria o diretório de segurança e importa a chave GPG oficial do Docker

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | 
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg




# Registra o repositório estável do Docker conforme a versão do sistema

echo \

  "deb [arch=$(dpkg --print-architecture) 
signed-by=/etc/apt/keyrings/docker.gpg]
 https://download.docker.com/linux/ubuntu \

  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \

  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null




# Atualiza os índices e instala a engine oficial do Docker

sudo apt-get update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io 
docker-buildx-plugin docker-compose-plugin




# Habilita a inicialização automática do serviço

sudo systemctl enable --now docker




# Adiciona o usuário 'ubuntu' ao grupo Docker para dispensar 
o uso de sudo nos comandos

sudo usermod -aG docker ubuntu

 

3.3. Configuração do banco de dados

Para aplicações de produção que necessitam de persistência de dados, inicializaremos um contêiner PostgreSQL isolado, garantindo o funcionamento interno sem expor portas sensíveis à internet:

Bash

 

# Cria um volume persistente para proteger as informações 
fora do ciclo do contêiner

docker volume create pgdata




# Inicializa o contêiner do banco de dados amarrado ao localhost 
(127.0.0.1)

docker run -d \

  --name app-db \

  -e POSTGRES_USER=usuario_prod \

  -e POSTGRES_PASSWORD=<SENHA_SEGURA_DO_BANCO> \

  -e POSTGRES_DB=app_db_prod \

  -v pgdata:/var/lib/postgresql/data \

  --restart always \

  -p 127.0.0.1:5432:5432 \

  postgres:16-alpine

4. Preparação da aplicação para o modo SSR

No repositório do seu projeto (na sua máquina local de desenvolvimento), crie os arquivos de configuração necessários para otimizar o empacotamento da aplicação.

4.1. Dockerfile para projetos Next.js

Crie um arquivo chamado Dockerfile na raiz do seu projeto Next.js. O modelo abaixo utiliza múltiplos estágios para gerar uma imagem leve e otimizada:

Dockerfile

 

# Estágio de dependências e build

FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./

RUN npm ci

COPY . .

ENV NODE_ENV=production

RUN npm run build




# Estágio de execução (produção)

FROM node:18-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

ENV PORT=3000

ENV HOSTNAME="0.0.0.0"




# Copia apenas os artefatos mínimos e essenciais do build

COPY --from=builder /app/next.config.js ./

COPY --from=builder /app/public ./public

COPY --from=builder /app/.next/standalone ./

COPY --from=builder /app/.next/static ./.next/static




EXPOSE 3000

CMD ["node", "server.js"]

4.2. Dockerfile para projetos Nuxt.js

Se o seu framework de escolha for o Nuxt.js, utilize o seguinte modelo de Dockerfile na raiz do projeto:

Dockerfile

 

# Estágio de build

FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./

RUN npm ci

COPY . .

RUN npm run build




# Estágio de execução

FROM node:18-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

ENV NITRO_PORT=3000

ENV NITRO_HOST=0.0.0.0




# Copia o diretório de saída estruturado pelo Nitro

COPY --from=builder /app/.output ./.output




EXPOSE 3000

CMD ["node", ".output/server/index.mjs"]

5. Deploy: método moderno (Docker + GitHub Actions)

Automatizar suas publicações através de uma esteira de CI/CD (GitHub Actions) é a melhor prática para garantir agilidade, eliminar erros manuais e acelerar o seu time-to-market.

5.1. Workflow do GitHub Actions

Crie a estrutura de diretórios .github/workflows/ no seu projeto local e salve o arquivo deploy.yml:

YAML

name: CI/CD Deploy Locaweb Cloud




on:

  push:

    branches:

      - main




jobs:

  deploy:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout do código

        uses: actions/checkout@v4




      - name: Configurar chave SSH de acesso

        run: |

          mkdir -p ~/.ssh

          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa

          chmod 600 ~/.ssh/id_rsa

          ssh-keyscan -H ${{ secrets.SERVER_IP }} >> ~/.ssh/known_hosts




      - name: Enviar código para o servidor

        run: |

          rsync -avz --exclude '.git' --exclude 'node_modules' 
--exclude '.next' --exclude '.output' .
/ ubuntu@${{ secrets.SERVER_IP }}:/home/ubuntu/app/




      - name: Build e reinício do container na VM do Locaweb Cloud

        run: |

          ssh ubuntu@${{ secrets.SERVER_IP }} << 'EOF'

            cd /home/ubuntu/app

            docker build -t minha-app-ssr:latest .

            docker stop minha-app-instancia || true

            docker rm minha-app-instancia || true

            docker run -d \

              --name minha-app-instancia \

              -p 3000:3000 \

              --link app-db:db \

              -e DATABASE_URL="postgresql://usuario_prod:
<SENHA_SEGURA_DO_BANCO>@db:5432/app_db_prod" \

              --restart always \

              minha-app-ssr:latest

          EOF

5.2. Configuração das variáveis secretas (Secrets) no GitHub

No painel do seu repositório no GitHub, navegue até Settings > Secrets and variables > Actions e cadastre as chaves de segurança:

• SSH_PRIVATE_KEY: O conteúdo textual completo do arquivo da sua chave privada .key ou .pem.
• SERVER_IP: O endereço IP Público alocado para a sua VM.

 

6. Deploy: método manual (PM2)

Caso prefira rodar a aplicação diretamente no sistema operacional da instância sem utilizar contêineres, você pode contar com o PM2 para gerenciar os processos e manter a execução SSR ativa em segundo plano.

6.1. Instalação do Node.js e do PM2 na VM

No terminal da sua instância Linux, instale o gerenciador de versões (NVM) e o PM2:

Bash

 

# Baixa e instala o NVM (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/
install.sh|bash

source ~/.bashrc


# Instala a versão estável LTS do Node.js

nvm install --lts


# Instala globalmente o gerenciador de processos PM2

npm install -g pm2

6.2. Execução da aplicação

Clone o repositório diretamente na instância, instale os pacotes e gere a compilação:

Bash

git clone https://github.com/seu-usuario/seu-repositorio.git app-manual

cd app-manual

npm install

npm run build

Agora, inicie o processo SSR no ambiente do PM2 apontando para o seu framework:

Bash

# Se o projeto for Next.js:

pm2 start npm --name "next-ssr" -- start -- --port 3000


# Se o projeto for Nuxt.js:

pm2 start .output/server/index.mjs --name "nuxt-ssr"

Para garantir que a aplicação se recupere de forma automatizada caso o servidor sofra uma reinicialização:

Bash

# Integra os processos do PM2 ao systemd do sistema operacional

pm2 startup

# Execute o comando com 'sudo' gerado na tela do terminal para 
registrar o serviço




# Salva o estado atual dos processos para restauração automática 
no boot
pm2 save

 

7. Configuração do Nginx como Proxy Reverso e SSL (HTTPS)

Aplicações de produção modernas não devem expor a porta da engine Node.js diretamente ao tráfego público da internet. O Nginx funcionará como um proxy reverso para otimizar as requisições, aplicar regras de cabeçalho e realizar a terminação criptográfica de segurança.

7.1. Instalação e configuração do Nginx

Instale o servidor web e crie o arquivo de configuração dedicado para a sua aplicação:

Bash

sudo apt install nginx -y




# Remove o bloco de configuração padrão do sistema

sudo rm /etc/nginx/sites-enabled/default




# Abre um novo arquivo de configuração limpo

sudo nano /etc/nginx/sites-available/app-ssr

Insira o conteúdo abaixo no arquivo, ajustando o parâmetro server_name com o seu domínio real:

Nginx

server {

    listen 80;

    server_name app.suaempresa.com.br;




    client_max_body_size 20M;




    location / {

        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

        proxy_set_header Connection 'upgrade';

        proxy_set_header Host $host;

        proxy_cache_bypass $http_upgrade;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;

    }

}

Ative a configuração criando o link simbólico no sistema, valide a sintaxe do arquivo e reinicie o serviço do Nginx:

Bash

sudo ln -s /etc/nginx/sites-available/app-ssr /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl restart nginx

7.2. Instalação do Certificado SSL com Let’s Encrypt

Para proteger as informações e transações de dados dos seus usuários com o protocolo seguro HTTPS, ative o certificado SSL gratuito:

Bash

# Instala o Certbot utilitário e o módulo de integração com o Nginx

sudo apt install certbot python3-certbot-nginx -y


# Dispara a emissão automática do certificado Let's Encrypt
 para o seu domínio

sudo certbot --nginx -d app.suaempresa.com.br

Siga as orientações exibidas na tela do terminal. O assistente do Certbot aplicará as mudanças necessárias nas tabelas do Nginx, configurará o redirecionamento automático de HTTP para HTTPS e cuidará das rotinas de renovação periódica do protocolo.

8. Validação 

Com todas as etapas finalizadas, valide o sucesso da sua infraestrutura através de testes internos e externos.

8.1. Validação interna (dentro da VM)

Verifique se os contêineres do Docker estão ativos e saudáveis na camada do sistema:

Bash

docker ps

Se utilizou o gerenciador de processos PM2, certifique-se de mapear o status como online:

Bash

pm2 status

Realize uma requisição interna de teste para confirmar que a aplicação responde corretamente no servidor local:

Bash

curl -I http://127.0.0.1:3000

8.2. Validação externa (máquina local)

Abra o terminal do seu computador local e valide o comportamento do seu domínio apontado, certificando-se de receber o código de status HTTP 200 OK servido de forma protegida:

Bash

curl -I https://app.suaempresa.com.br

Bash

curl -v telnet://<SEU_IP_PUBLICO>:5432

9. Solução de problemas (Troubleshooting)

• Erro 502 Bad Gateway ao acessar o domínio: Indica que o Nginx está operacional, mas não consegue se conectar à aplicação Node.js. Verifique os logs do contêiner com docker ps ou consulte as saídas do PM2 com pm2 logs. Certifique-se de que a aplicação está ativa escutando a porta 3000.
• Falha de compilação por falta de memória (Out of Memory): Caso o comando npm run build sofra quedas com o erro JavaScript heap out of memory, crie uma partição de swap temporária para atuar como memória virtual auxiliar no sistema operacional:

Bash

sudo fallocate -l 2G /swapfile

sudo chmod 600 /swapfile

sudo mkswap /swapfile

sudo swapon /swapfile

echo '/swapfile none swap sw,nofail 0 0' | sudo tee -a /etc/fstab

Acesso recusado via SSH (Permission denied): Acesso via SSH negado (Permission denied): Antes de tentar a conexão, certifique-se de que as permissões de segurança do arquivo de chave privada em seu computador local foram configuradas corretamente. Utilize o comando chmod 400 sua-chave.key para garantir que apenas o seu usuário tenha acesso ao arquivo, prevenindo bloqueios por chaves excessivamente expostas.