Hospedagem do Hermes via Containers no Locaweb Cloud

Pré-requisitos

Para acompanhar a implementação arquitetural deste guia, certifique-se de cumprir os seguintes requisitos:

• Conta ativa no Locaweb Cloud: com acesso liberado ao painel de controle.
• Chave de autenticação SSH: uma chave privada SSH (arquivo .key ou .pem) gerada e com a respectiva chave pública cadastrada no painel do Locaweb Cloud. No seu terminal local, ajuste a permissão da chave privada com chmod 400 sua-chave.key.
• Conhecimento básico de terminal: familiaridade com navegação de diretórios e uso do gerenciador de pacotes em ambientes Linux.
• (Opcional) Domínio próprio: um domínio ou subdomínio apontando para o IP público da VM de aplicação, necessário para emitir um certificado HTTPS gratuito com Let’s Encrypt.

2. Configuração de infraestrutura (painel)

A base de uma aplicação segura é o isolamento de rede. Criaremos uma Virtual Private Cloud (VPC) para abrigar nossos servidores, garantindo que o banco de dados não seja exposto diretamente à internet.

2.1. Criação da Rede VPC e Tiers

1. Navegue até Rede > VPC no painel do Locaweb Cloud e clique em Adicionar VPC.
2. Defina o bloco CIDR principal (exemplo: 10.0.0.0/16) e selecione a Oferta de VPC adequada ao seu projeto.
3. Dentro da nova VPC, acesse a aba Redes e clique em Adicionar novo tier.
4. Crie um tier chamado Tier-Aplicacao (exemplo de CIDR: 10.0.1.0/24) para o servidor do Hermes e outro chamado Tier-BancoDados (exemplo de CIDR: 10.0.2.0/24) para o PostgreSQL.

2.2. Provisionamento das Máquinas Virtuais (VMs)

Serão necessárias duas instâncias: uma para o banco de dados e outra para a aplicação.

1. Navegue até Computação > VMs e clique em Adicionar VM.
2. VM de Banco de Dados:
   • Template: selecione Ubuntu 22.04 LTS.
   • Oferta: escolha um plano com recursos de CPU e RAM otimizados para banco de dados (exemplo: 4 vCPUs, 8 GB de RAM).
   • Rede: conecte ao Tier-BancoDados.
   • Chave SSH: selecione a sua chave pública previamente cadastrada.
   • Disco secundário: durante a criação, adicione um Datadisk (ex.: 50 GB) que será usado para persistir os dados do PostgreSQL.
3. VM da Aplicação (Hermes):
   • Repita o processo, escolhendo um plano adequado para a carga do Hermes (exemplo: 2 vCPUs, 4 GB de RAM).
   • Template: Ubuntu 22.04 LTS.
   • Rede: conecte ao Tier-Aplicacao.
   • Chave SSH: selecione a mesma chave pública cadastrada.

2.3. IPs Públicos, encaminhamento de porta e regras de Firewall

A VM de banco de dados permanecerá isolada, comunicando-se apenas com a VM da aplicação via IP privado. Para a VM do Hermes receber tráfego web:

1. Acesse Rede > VPC > [Sua VPC] > IPs Públicos e clique em Obter um novo IP.
2. Selecione o IP adquirido e vá para a aba Encaminhamento de porta. Crie regras direcionando as portas públicas para a VM do Hermes conforme a tabela abaixo:

Porta pública	Porta privada	Protocolo	Destino
80 (HTTP)	80	TCP	VM do Hermes
443 (HTTPS)	443	TCP	VM do Hermes
22 (SSH)	22	TCP	VM do Hermes

 

1. Na aba Firewall, adicione regras de entrada liberando o tráfego TCP nas portas 80, 443 e 22. Para a porta 22 (SSH), recomendamos fortemente restringir o CIDR de origem ao IP da sua rede de administração (exemplo: <SEU_IP_ADMIN>/32), em vez de liberar 0.0.0.0/0.

1.4. ACL de rede entre os Tiers

Para que a VM da aplicação alcance o banco de dados pela rede privada, configure a ACL da VPC permitindo o tráfego da sub-rede de aplicação até a porta do PostgreSQL:

Origem (CIDR)	Destino	Protocolo	Porta	Ação
10.0.1.0/24 (Tier-Aplicacao)	Tier-BancoDados	TCP	5432	Permitir
0.0.0.0/0	Tier-BancoDados	TCP	5432	Negar

 

3. Preparação do disco de dados na VM de banco de dados

Para que os dados do PostgreSQL sobrevivam a reinicializações e recriações da instância, vamos formatar e montar o disco secundário de forma persistente. Acesse a VM de banco de dados via SSH (fazendo um salto a partir da VM de aplicação, já que o banco não possui IP público) e execute os comandos:

Bash

# Lista os discos disponíveis para identificar o disco secundário (geralmente /dev/vdb)

lsblk


# Cria o sistema de arquivos ext4 no disco secundário identificado

sudo mkfs.ext4 /dev/vdb


# Cria o ponto de montagem onde os dados do PostgreSQL serão armazenados

sudo mkdir -p /mnt/dados

 

Em vez de referenciar o disco pelo nome do dispositivo (que pode mudar de ordem entre reinicializações), usamos o UUID estável no /etc/fstab:

Bash

# Exibe o UUID do disco secundário

sudo blkid /dev/vdb

# Copie o valor de UUID exibido na saída



# Adiciona a montagem permanente usando o UUID (substitua <SEU_UUID>)

echo 'UUID=<SEU_UUID>  /mnt/dados  ext4  defaults,nofail,noatime  0  2' | sudo tee -a /etc/fstab



# Monta todos os pontos definidos no fstab e confirma o resultado

sudo mount -a

df -h /mnt/dados

 

4. Configuração do banco de dados no Locaweb Cloud

Como estamos operando em IaaS, o banco de dados é configurado dentro da VM designada no Tier-BancoDados. Ainda conectado a essa VM via SSH, instale o PostgreSQL:

Bash

# Atualiza os repositórios locais para garantir o download das versões mais recentes

sudo apt-get update




# Instala o servidor PostgreSQL e pacotes adicionais

sudo apt-get install -y postgresql postgresql-contrib




# Inicia o serviço e garante sua execução automática na inicialização do sistema

sudo systemctl enable --now postgresql

4.1. Apontando o PostgreSQL para o disco persistente

Para armazenar os dados no disco secundário montado em /mnt/dados, mova o diretório de dados do PostgreSQL:

Bash

# Para o serviço antes de mover os dados

sudo systemctl stop postgresql




# Move o diretório de dados padrão para o disco persistente (ajuste a versão se necessário)

sudo rsync -av /var/lib/postgresql/14/main/ /mnt/dados/postgresql/




# Ajusta o dono do novo diretório para o usuário do PostgreSQL

sudo chown -R postgres:postgres /mnt/dados/postgresql

Edite o arquivo de configuração para apontar o data_directory para o novo local e habilitar a escuta na rede privada:

Bash

sudo nano /etc/postgresql/14/main/postgresql.conf

 

Ajuste as linhas a seguir no arquivo:

Snippet de código

data_directory = '/mnt/dados/postgresql'

listen_addresses = '10.0.2.X'   # IP privado da VM de Banco de Dados no Tier-BancoDados

 

4.2. Criação do usuário, do banco e regra de acesso

Crie o usuário e o banco que o Hermes utilizará:

Bash

# Acessa o console administrativo do PostgreSQL

sudo -u postgres psql

 

No prompt do psql, execute os comandos de infraestrutura:

SQL

CREATE DATABASE hermes_db;

CREATE USER hermes_user WITH ENCRYPTED PASSWORD 'SUA_SENHA_FORTE_AQUI';

GRANT ALL PRIVILEGES ON DATABASE hermes_db TO hermes_user;

\q

 

Em seguida, restrinja o acesso de rede para que apenas a sub-rede de aplicação possa se conectar. Edite o arquivo de controle de acesso:

Bash

sudo nano /etc/postgresql/14/main/pg_hba.conf

Adicione a linha abaixo, liberando conexões apenas da sub-rede do Tier-Aplicacao:

Snippet de código

# Permite conexões criptografadas apenas da sub-rede da aplicação

host    hermes_db    hermes_user    10.0.1.0/24    scram-sha-256

Aplique as alterações reiniciando o serviço:

Bash

# Reinicia o PostgreSQL para carregar o novo data_directory e as regras de acesso

sudo systemctl restart postgresql

 

5. Configuração do sistema e Docker (passo a passo no Terminal)

Agora, configuraremos o ambiente de execução do Hermes na VM de aplicação conectada ao Tier-Aplicacao.

5.1. Acesso remoto

Conecte-se à VM de aplicação usando a chave SSH configurada e o IP público mapeado. Substitua o caminho da chave e o IP pelos seus valores correspondentes:

Bash

# Conecta à VM de aplicação via SSH usando a chave privada

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

5.2. Instalação do ambiente de Containers

Utilizaremos Docker para garantir a portabilidade e a consistência do ambiente do Hermes. A instalação é feita pelo repositório oficial do Docker, garantindo pacotes assinados e atualizações controladas:

Bash

# Atualiza o índice de pacotes e instala dependências para repositórios HTTPS

sudo apt-get update

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




# Cria o diretório oficial de chaves do APT

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




# Adiciona a chave GPG oficial do Docker para verificação de assinaturas

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




# Adiciona o repositório estável do Docker ao 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




# Instala o Docker Engine, a CLI 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 Docker para iniciar junto com o sistema

sudo systemctl enable --now docker




# Adiciona o usuário atual ao grupo docker para executar comandos sem 'sudo'

sudo usermod -aG docker $USER

5. Estratégias de deploy do Hermes

Com a infraestrutura pronta, você possui total autonomia para optar pela abordagem de deploy mais alinhada ao tempo de mercado (time-to-market) do seu fluxo de desenvolvimento.

Abordagem A: Método manual via Git Pull (Tradicional)

Indicado para arquiteturas simples ou fases iniciais de validação:

Bash

# Cria o diretório da aplicação e clona o repositório oficial do Hermes

sudo mkdir -p /opt/hermes && sudo chown $USER:$USER /opt/hermes

cd /opt/hermes

git clone https://github.com/seu-usuario/hermes.git .




# Cria e edita o arquivo de variáveis de ambiente (.env) com a string de conexão do banco

cat <<EOF > .env

DB_HOST=10.0.2.X            # IP privado da VM de Banco de Dados na Locaweb Cloud

DB_PORT=5432

DB_USER=hermes_user

DB_PASS=SUA_SENHA_FORTE_AQUI

DB_NAME=hermes_db

DATABASE_URL=postgresql://hermes_user:SUA_SENHA_FORTE_AQUI@10.0.2.X:5432/hermes_db

EOF




# Sobe os containers em modo detached (segundo plano)

docker compose up -d

O comando docker compose up -d lê o arquivo docker-compose.yml do projeto, efetua o pull das imagens necessárias e orquestra a execução dos containers de forma automatizada. As variáveis definidas em .env (incluindo a DATABASE_URL) são lidas pelo Hermes para estabelecer a comunicação direta com o PostgreSQL no Tier-BancoDados.

Abordagem B: Método moderno via GitHub Actions (CI/CD Automático)

Para ambientes de produção profissionais, recomenda-se automatizar a entrega. A principal vantagem é eliminar tarefas repetitivas: toda alteração validada na branch principal é publicada na plataforma de forma consistente e estável, reduzindo drasticamente falhas manuais.

No seu repositório do GitHub, acesse Settings > Secrets and variables > Actions e cadastre as seguintes chaves de segurança (Secrets):

• HOST_IP: o endereço IP público da sua VM de aplicação.
• SSH_USER: o usuário de acesso do sistema operacional (exemplo: ubuntu).
• SSH_KEY: o conteúdo completo da sua chave privada SSH.

Em seguida, crie o arquivo de automação estruturado em .github/workflows/deploy.yml:

YAML

name: Deploy Hermes to Locaweb Cloud




on:

  push:

    branches: [ "main" ]




jobs:

  deploy:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout do código

        uses: actions/checkout@v4




      - name: Executar comandos via SSH

        uses: appleboy/ssh-action@v1.0.3

        with:

          host: ${{ secrets.HOST_IP }}

          username: ${{ secrets.SSH_USER }}

          key: ${{ secrets.SSH_KEY }}

          script: |

            cd /opt/hermes

            git pull origin main

            docker compose pull

            docker compose up -d --remove-orphans

 

Essa estratégia garante agilidade e eficiência total, assegurando que o seu código vire negócio em tempo recorde assim que passar pelo repositório Git.

7. Configuração de HTTPS com Let’s Encrypt

Expor o Hermes apenas através do protocolo HTTP coloca os dados trafegados em risco. O ideal é implementar uma barreira de segurança com o Nginx atuando como proxy reverso na frente da aplicação para emitir um certificado gratuito com o Let’s Encrypt. Na VM de aplicação, execute:

Bash

# Instala o Nginx, o Certbot e o plugin de integração com o Nginx

sudo apt-get update

sudo apt-get install -y nginx certbot python3-certbot-nginx

 

Crie o arquivo de configuração do site, encaminhando as requisições para o container do Hermes (ajuste a porta interna conforme o mapeamento do seu docker-compose.yml):

Bash

sudo nano /etc/nginx/sites-available/hermes.conf

 

Insira o conteúdo estruturado abaixo:

Nginx

server {

    listen 80;

    server_name <SEU_DOMINIO>;




    location / {

        proxy_pass http://localhost:3000;

        proxy_set_header Host $host;

        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 as configurações no Nginx e emita o certificado de segurança:

Bash

# Habilita o site e remove o site padrão para evitar conflitos na camada de rede

sudo ln -s /etc/nginx/sites-available/hermes.conf /etc/nginx/sites-enabled/

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




# Testa a configuração e recarrega o serviço do Nginx

sudo nginx -t

sudo systemctl reload nginx




# Emite e instala o certificado SSL, ativando o redirecionamento automático de HTTP para HTTPS

sudo certbot --nginx -d <SEU_DOMINIO>

8. Validação

Para confirmar o sucesso na orquestração dos recursos de IaaS e garantir que a sua operação está centralizada e rodando sem gargalos, execute os testes de validação técnica descritos a seguir.

8.1. Testes internos na VM de aplicação

Bash

# Lista os containers em execução; o status deve indicar "Up"

docker ps




# Verifica os cabeçalhos de resposta da aplicação localmente

curl -I http://localhost:3000

 

O comando docker ps deve listar o container do Hermes ativo. O curl deve retornar o código de status esperado pela aplicação (como HTTP/1.1 200 OK). Para auditar a integridade técnica e monitorar a conexão com o PostgreSQL em tempo real:

Bash

# Acompanha os logs do container em tempo real (-f mantém a leitura ativa)

docker logs -f hermes_app_container

8.2. Teste externo a partir da sua máquina local

A partir do seu computador de administração conectado à internet, valide o acesso público seguro através da URL do seu domínio próprio:

Bash

# Verifica a resposta HTTPS a partir da internet

curl -I https://<SEU_DOMINIO>

A resposta esperada é um cabeçalho HTTP/2 200, exibindo as propriedades do TLS e atestando que o encaminhamento de portas e o Firewall estão operando perfeitamente.

8.3. Teste de isolamento do banco de dados

Para certificar-se de que a camada de dados não sofre com a exposição a acessos maliciosos externos, realize uma checagem de portas a partir da sua máquina local direcionada ao IP público da infraestrutura:

Bash

# A conexão DEVE falhar (timeout), comprovando o isolamento do banco

nc -vz <SEU_IP_PUBLICO> 5432

O resultado esperado é um esgotamento de tempo de conexão (Connection timed out). Caso a conexão seja bem-sucedida, revise imediatamente as parametrizações de Firewall no painel, pois o banco estará vulnerável.

9. Solução de problemas (Troubleshooting)

• Permissão SSH negada
  • Sintoma: o terminal exibe a mensagem Permission denied (publickey) durante o acesso remoto.
  • Causa: as permissões do arquivo de chave privada estão excessivamente abertas no computador local ou o par público associado não corresponde ao cadastrado na VM.
  • Solução: execute o comando chmod 400 sua-chave.key no seu terminal e certifique-se de especificar o usuário master correto (ubuntu) no comando de conexão.
• Aplicação inacessível através da internet
  • Sintoma: o comando curl -I https://<SEU_DOMINIO> atinge tempo limite (timeout), mas o tráfego interno em http://localhost:3000 funciona dentro da VM.
  • Causa: ausência de regras de Encaminhamento de Porta ou Firewall para as portas 80/443 no painel administrativo, ou atraso na propagação de DNS do domínio.
  • Solução: acesse as abas de rede no painel do Locaweb Cloud, valide se as portas 80 e 443 estão direcionadas para o IP privado da VM do Hermes e execute um diagnóstico de rede com dig <SEU_DOMINIO> para conferir o apontamento.
• Container do Hermes apresenta falhas ao conectar ao PostgreSQL
  • Sintoma: o comando docker logs indica erros intermitentes de conexão com a base de dados (timeout ou autenticação rejeitada).
  • Causa: o parâmetro listen_addresses no banco não engloba a rede privada, as chaves do pg_hba.conf barram a origem ou as regras de ACL da VPC impedem o tráfego na porta 5432.
  • Solução: valide as linhas do postgresql.conf e pg_hba.conf no servidor de dados, certifique-se de reiniciar o serviço do PostgreSQL e confira a tabela de ACL da VPC liberando o tráfego entre as sub-redes.
• Container em estado de encerramento (“Exited”)
  • Sintoma: o comando docker ps -a indica que a aplicação encerrou a execução abruptamente.
  • Causa: parametrização incorreta de variáveis de ambiente no arquivo .env ou ausência da propriedade DATABASE_URL.
  • Solução: inspecione os logs técnicos com docker logs hermes_app_container, realize as correções necessárias nas strings do arquivo .env e execute novamente o deploy com docker compose up -d.