Como fazer deploy de uma API REST (Express/Fastify) com Docker no Locaweb Cloud

 

O uso de containers Docker no Locaweb Cloud profissionaliza sua infraestrutura, substituindo configurações manuais por imagens imutáveis que encapsulam toda a aplicação e dependências.

1. Pré-requisitos

Antes de iniciar os comandos no terminal, certifique-se de que os seguintes requisitos estão atendidos:

• Conta Locaweb Cloud ativa com acesso ao painel.
• Máquina virtual (VM) Linux ativa (recomendado: Ubuntu 22.04 LTS).
• Chave SSH privada (.key ou .pem) salva localmente.
• Repositório Git com o código-fonte da sua API REST versionado no GitHub.

 

2. Configuração de infraestrutura (painel CloudStack)

Antes de rodar qualquer comando no terminal, é necessário preparar a rede para que sua VM seja alcançável pela internet e, ao mesmo tempo, manter o banco de dados isolado. Faça login no seu painel administrativo e siga os passos:

Passo 1: Obter o IP Público

1. No menu lateral, acesse Rede > Endereços IP Públicos.
2. Localize o IP público associado à sua rede. Anote esse endereço; ele será o seu <SEU_IP_PUBLICO>.

Passo 2: Configurar o Encaminhamento de Portas (Port Forwarding)

O encaminhamento de portas direciona o tráfego externo para o IP interno da sua VM. Acesse a aba Encaminhamento de Portas (Port Forwarding) e crie as seguintes regras:

Regra	Porta Pública	Porta Privada	Protocolo	VM de Destino
SSH	22 / 22	22 / 22	TCP	sua-vm
HTTP	80 / 80	80 / 80	TCP	sua-vm
API (Opcional)	3000 / 3000	3000 / 3000	TCP	sua-vm

 

Passo 3: Liberar as portas no Firewall

Na tela do IP público, abra a aba Firewall e crie as regras de entrada correspondentes:

Origem (CIDR)	Porta (Inicial/Final)	Protocolo	Observação
<SEU_IP_DE_ADMIN>/32	22 / 22	TCP	SSH restrito ao seu IP de administração
0.0.0.0/0	80 / 80	TCP	HTTP público
0.0.0.0/0	3000 / 3000	TCP	Liberado apenas se utilizou a regra opcional

 

3. Configuração do sistema: instalação do Docker na VM

Acesse sua máquina virtual pelo terminal local para instalar o Docker Engine e o utilitário Docker Compose.

Passo 1: Acessar a Máquina Virtual via SSH

Bash

# Define a permissão restrita na chave privada por segurança

chmod 400 ~/Downloads/sua-chave-locaweb.key

# Estabelece a conexão remota com a VM Linux
ssh -i ~/Downloads/sua-chave-locaweb.key ubuntu@<SEU_IP_PUBLICO>

Passo 2: Instalar o Docker Engine

Bash

# Atualiza os índices do sistema e instala dependências HTTPS

sudo apt-get update

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



# Adiciona a chave oficial de GPG 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



# Configura o repositório estável oficial do Docker

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



# Instala o motor do Docker e o plugin do Docker Compose

sudo apt-get update

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



# Habilita o serviço para inicializar junto com o servidor

sudo systemctl enable --now docker

Passo 3: Configurar permissões do grupo

Bash

# Adiciona o usuário ao grupo docker para não depender do 
comando 'sudo'

sudo usermod -aG docker ubuntu

 

Nota: Encerre a sessão SSH e reconecte-se para aplicar as permissões do grupo.

4. Configuração do banco de dados: PostgreSQL em Container

Os dados da nossa API serão armazenados em uma instância de PostgreSQL, que operará de forma isolada dentro de um container. A definição deste serviço ocorrerá integralmente dentro do arquivo docker-compose.yml, mantendo a porta 5432 protegida de acessos externos. A aplicação o alcançará internamente pelo hostname db:

Plaintext

DATABASE_URL=postgresql://api_user:<SENHA_SEGURA_DO_BANCO>@db:5432/
api_producao

5. Preparação da aplicação 

Na raiz do seu projeto local, crie os arquivos de automação do deploy:

Dockerfile

Dockerfile

FROM node:20-alpine

WORKDIR /usr/src/app

COPY package*.json ./

RUN npm ci --omit=dev

COPY . .

EXPOSE 3000

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

  .dockerignore

Plaintext

node_modules

npm-debug.log

.git

.github

.env

docker-compose.yml

YAML

services:

  api:

    build: .

    container_name: api-producao

    restart: always

    ports:

      - "3000:3000"

    env_file:

      - .env

    depends_on:

      - db




  db:

    image: postgres:16-alpine

    container_name: postgres-producao

    restart: always

    environment:

      POSTGRES_USER: api_user

      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

      POSTGRES_DB: api_producao

    volumes:

      - pgdata:/var/lib/postgresql/data




volumes:

  pgdata:

6. Deploy da Aplicação

Escolha o método ideal para o seu momento de mercado:

Método 1: Deploy manual via Git (primeira validação)

Bash

# Cria o diretório de aplicações e clona seu repositório Git

sudo mkdir -p /var/www && sudo chown ubuntu:ubuntu /var/www

cd /var/www

git clone https://github.com/seu-usuario/sua-api-rest.git

cd sua-api-rest




# Configura as variáveis de ambiente de produção

nano .env

Adicione suas variáveis de ambiente no arquivo .env mapeando a senha e a URL de conexão do banco interna.

Bash

# Inicializa a stack de serviços em segundo plano

docker compose up -d --build

Método 2: Deploy automatizado com GitHub Actions (recomendado)

Adicione os Secrets no seu repositório do GitHub (SSH_HOST, SSH_USERNAME, SSH_KEY) e crie o arquivo .github/workflows/deploy-docker.yml:

YAML

name: Deploy Docker Locaweb Cloud


on:

  push:

    branches:

      - main



jobs:

  deploy:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout do Código

        uses: actions/checkout@v4




      - name: Deploy via SSH no Locaweb Cloud

        uses: appleboy/ssh-action@v1.0.3

        with:

          host: ${{ secrets.SSH_HOST }}

          username: ${{ secrets.SSH_USERNAME }}

          key: ${{ secrets.SSH_KEY }}

          port: 22

          script: |

            cd /var/www/sua-api-rest

            git reset --hard HEAD

            git pull origin main

            docker compose up -d --build

7. Validação 

Validação interna (na VM)

Bash

# Confirma se os containers estão com status 'Up'

docker compose ps


# Verifica os logs em tempo real da API

docker compose logs -f api

Validação externa (máquina local)

Bash

# Testa a resposta pública da API através do IP público

curl -I http://<SEU_IP_PUBLICO>:3000

O retorno esperado é o cabeçalho HTTP 200 OK. Caso ocorra timeout, valide as regras de Firewall e Port Forwarding no painel CloudStack.

Validação de isolamento do banco

Bash

# Garante que a porta 5432 do banco está blindada contra a internet

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

O comportamento correto e seguro para esse teste é apresentar uma FALHA de conexão, comprovando o isolamento do banco de dados.

8. Solução de problemas (Troubleshooting)

 

• Permissão SSH Negada (Permission denied): Garanta que executou o comando chmod 400 na sua chave privada local antes de se conectar.
• Container com status Exited: Rode docker compose logs api para inspecionar os erros de inicialização do Node.js. Certifique-se de que a string DATABASE_URL aponta para db e não para localhost.
• Erro docker: permission denied: Significa que o usuário ainda não foi sincronizado com o grupo. Encerre sua sessão SSH atual e reconecte-se para atualizar as diretrizes.

Próximos Passos recomendados para produção:

1. Habilitar HTTPS com Let’s Encrypt: Configure um proxy reverso Nginx na máquina virtual para criptografar as requisições web. Lembre-se de liberar a porta 443 nas regras de Firewall do painel.
2. Backups automatizados: Crie rotinas periódicas de pg_dump para salvaguardar o banco de dados.