Deploy de API FastAPI com PostgreSQL no Locaweb Cloud

Apresentamos a seguir o detalhamento da arquitetura de rede que será implementada ao longo deste guia. A estrutura foi desenhada para que a API opere em uma sub-rede pública, com acesso restrito à porta da aplicação, enquanto o banco de dados PostgreSQL permanece protegido e invisível em uma sub-rede privada:

 

                  [ Internet ]

                       │

                       ▼ (IP Público Fixo)

              [ Roteador Virtual / Firewall ]

                       │

         ┌─────────────┴─────────────┐

         ▼ (Porta 8000)              ▼ (Bloqueado)

   ┌──────────────────┐        ┌──────────────────┐

   │ Tier-Publica-Web │        │ Tier-DB          │

   │ 10.0.1.0/24      │        │ 10.0.2.0/24      │

   ├──────────────────┤        ├──────────────────┤

   │  ┌────────────┐  │        │  ┌────────────┐  │

   │  │ VM API     │  │──────► │  │ VM Postgres│  │

   │  │ (FastAPI)  │  │ (5432) │  │ (Database) │  │

   │  │            │  │        │  │            │  │

   │  └────────────┘  │        │  └────────────┘  │

   └──────────────────┘        └──────────────────┘

 

1. Pré-requisitos

Para garantir que o código vira negócio sem fricção, valide os seguintes pré-requisitos antes de iniciar os comandos:

• Conta Locaweb Cloud ativa com acesso administrativo ao painel CloudStack.
• Par de chaves SSH cadastrado na plataforma para autenticação segura.
• Máquina local com um cliente SSH ativo no terminal.
• Um domínio de site registrado (opcional para o deploy inicial, mas mandatório para ativar o HTTPS posteriormente).

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

Toda a infraestrutura de rede e as máquinas virtuais devem ser provisionadas diretamente no painel administrativo antes de qualquer comando no terminal. Utilizaremos uma VPC (Virtual Private Cloud) para garantir o isolamento total do ambiente.

Passo 1: Criar a VPC

1. Acesse o painel do Locaweb Cloud e navegue até Rede > VPC > Adicionar VPC.
2. Configure os parâmetros da nova rede:
   • Nome: VPC-Producao-API
   • Zona: Selecione a zona de disponibilidade principal (ex: ZP01).
   • CIDR: 10.0.0.0/16
   • DNS 1 e 2: 8.8.8.8 e 8.8.4.4 (Google DNS).
3. Salve as alterações e aguarde a criação do seu roteador virtual dedicado.

Passo 2: Criar as Sub-redes (Tiers)

Dentro da VPC estruturada, criaremos duas Tiers para separar as responsabilidades do ecossistema:

1. Tier da API (Pública):
   • Nome: Tier-Publica-Web
   • Oferta de rede: Padrão com conectividade externa.
   • Gateway / CIDR: Gateway 10.0.1.1 e CIDR 10.0.1.0/24.
2. Tier do Banco de Dados (Privada):
   • Nome: Tier-DB
   • Oferta de rede: Rede privada (sem conectividade externa).
   • Gateway / CIDR: Gateway 10.0.2.1 e CIDR 10.0.2.0/24.
   • ACL: Selecione default_deny para bloquear acessos por padrão.

Passo 3: Configurar as ACLs da Tier do banco de dados

A sub-rede do banco só deve aceitar tráfego originado da sub-rede da aplicação. Na lista de ACLs da VPC, edite as regras de entrada (Ingress) da Tier-DB:

Número	CIDR de Origem	Protocolo	Porta Inicial	Porta Final	Ação
10	10.0.1.0/24	TCP	5432	5432	Allow
20	10.0.1.0/24	TCP	22	22	Allow
100	0.0.0.0/0	TCP	1	65535	Deny

 

Passo 4: Provisionar as máquinas virtuais

No menu Computação > Instâncias, adicione duas VMs utilizando a imagem oficial do Ubuntu 22.04 LTS:

1. VM-FastAPI-Prod: Vincule à rede VPC-Producao-API e associe à sub-rede pública Tier-Publica-Web (Mínimo recomendado: 2 vCPUs e 4 GB de RAM).
2. VM-Postgres-Prod: Vincule à rede VPC-Producao-API e associe à sub-rede privada Tier-DB (Mínimo recomendado: 2 vCPUs, 4 GB de RAM e armazenamento SSD).

Aguarde até que ambas fiquem com o status Running (Em execução) e anote seus IPs privados (ex: 10.0.1.15 para a API e 10.0.2.15 para o banco).

Passo 5: Alocar o IP Público e configurar Port Forwarding

1. Em Rede > VPC, selecione a sua VPC e mude para a aba IPs Públicos para obter um novo endereço IPv4 fixo.
2. Acesse a aba Encaminhamento de porta (Port Forwarding) desse IP e configure o redirecionamento para expor apenas a aplicação:

Protocolo	Porta Pública	Porta Privada	VM de Destino	Finalidade
TCP	8000	8000	VM-FastAPI-Prod	Tráfego da API FastAPI
TCP	22	22	VM-FastAPI-Prod	Acesso SSH Administrativo

 

Passo 6: Liberar as portas no Firewall

Na aba Firewall do seu IP público, autorize a entrada de pacotes correspondente ao mapeamento anterior:

CIDR de Origem	Protocolo	Porta Inicial	Porta Final	Finalidade
0.0.0.0/0	TCP	8000	8000	Acesso público à API
<SEU_IP_FIXO>/32	TCP	22	22	SSH restrito à sua rede de TI

3. Configuração de sistema (Terminal)

Com a infraestrutura provisionada no painel administrativo, acesse o terminal do servidor para preparar o ecossistema.

3.1. Conectar via SSH à VM da API

Utilize o terminal do seu computador local para configurar as permissões de segurança da sua chave privada e, em seguida, realize o acesso à instância pública:

Bash

chmod 400 ~/.ssh/sua-chave.key

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

Atualize os repositórios do sistema operacional e instale a engine oficial do Docker para garantir a velocidade de entrada no mercado:

Bash

# Atualiza pacotes e dependências de segurança

sudo apt-get update -y && sudo apt-get upgrade -y

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




# Configura a chave de criptografia estável do repositório 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 a fonte de pacotes oficial do Docker no gerenciador apt

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 e o plugin do Docker Compose

sudo apt-get update -y

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




# Habilita o serviço em segundo plano e adiciona permissões ao usuário 'ubuntu'

sudo systemctl enable --now docker

sudo usermod -aG docker ubuntu

3.2. Configuração do banco de dados (PostgreSQL)

A partir da VM da API, conecte-se à VM do banco utilizando a infraestrutura da rede privada interna da VPC:

Bash

ssh -i ~/.ssh/sua-chave.key ubuntu@10.0.2.15

Instale o banco dedicado para obter total autonomia sobre as tabelas e o desempenho de escrita:

Bash

sudo apt-get update -y

sudo apt-get install -y postgresql postgresql-contrib

sudo systemctl enable --now postgresql

Acesse o console administrativo nativo do PostgreSQL para criar as credenciais da API. Lembre-se de substituir a senha de exemplo por uma credencial forte:

Bash

sudo -u postgres psql

SQL

-- Executado dentro do console psql

CREATE DATABASE fastapi_prod;

CREATE USER fastapi_user WITH ENCRYPTED PASSWORD 'TroqueEstaSenha_2026!';

GRANT ALL PRIVILEGES ON DATABASE fastapi_prod TO fastapi_user;




-- Conecta ao banco para liberar permissões no schema public (PostgreSQL 15+)

\c fastapi_prod

GRANT ALL ON SCHEMA public TO fastapi_user;

\q

3.3. Configurar o acesso isolado de rede

Para que o banco de dados receba as conexões da sub-rede onde a aplicação está hospedada, é necessário ajustar o arquivo de configuração principal. Modifique o caminho abaixo substituindo o número da versão (como /14/ ou /15/) de acordo com o que foi instalado no seu ambiente:

Bash

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

Altere a diretriz de escuta para monitorar o IP privado local:

Nginx

listen_addresses = 'localhost,10.0.2.15'

Em seguida, abra o arquivo de políticas de hosts para autorizar apenas o tráfego originado na sub-rede da API (10.0.1.0/24):

Bash

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

Adicione a regra de conformidade técnica ao final do arquivo:

# TYPE  DATABASE      USER          ADDRESS        METHOD

host    fastapi_prod  fastapi_user  10.0.1.0/24    scram-sha-256

Salve o arquivo e reinicie o serviço do PostgreSQL para aplicar as novas chaves de segurança de rede:

Bash

sudo systemctl restart postgresql

4. Deploy da aplicação

Anote a string de conexão estruturada abaixo, que será usada pela engine do FastAPI para alcançar a sub-rede privada:

DATABASE_URL=postgresql://fastapi_user:TroqueEstaSenha_2026!@10.0.2.15:5432/fastapi_prod

Retorne à sua instância de aplicação (VM-FastAPI-Prod) via SSH para estruturar os arquivos do projeto.

4.1. Estrutura de arquivos

Crie a pasta do projeto no servidor:

Bash

mkdir -p ~/app-fastapi && cd ~/app-fastapi

Crie o arquivo básico de rotas main.py com validação de saúde do banco:

Python

# main.py

import os

from fastapi import FastAPI

from sqlalchemy import create_engine, text




app = FastAPI(title="API FastAPI no Locaweb Cloud")

DATABASE_URL = os.getenv("DATABASE_URL")

engine = create_engine(DATABASE_URL)





@app.get("/")

def read_root():

    return {

        "status": "ok",

        "mensagem": "API FastAPI em produção no Locaweb Cloud",

    }





@app.get("/health")

def health_check():

    with engine.connect() as conn:

        conn.execute(text("SELECT 1"))

    return {"database": "conectado"}

Crie a lista de dependências requirements.txt:

fastapi==0.111.0

uvicorn[standard]==0.30.1

sqlalchemy==2.0.31

psycopg2-binary==2.9.9

Crie o Dockerfile responsável por empacotar a aplicação de forma enxuta:

Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Crie o arquivo de orquestração docker-compose.yml:

YAML

services:

  api:

    build: .

    container_name: fastapi-prod

    restart: always

    ports:

      - "8000:8000"

    environment:

      - DATABASE_URL=postgresql://fastapi_user:TroqueEstaSenha_2026!@10.0.2.15:5432/fastapi_prod

 

Método 1: Deploy manual

Com os arquivos salvos no diretório, inicialize a sua aplicação em formato autosserviço:

Bash

# Constrói as camadas de imagem e roda o container em segundo plano

docker compose up -d --build

docker compose ps

 

Método 2: Deploy automatizado (GitHub Actions)

Para automatizar seu fluxo via Git e acelerar suas entregas, configure uma esteira de CI/CD cadastrando os seguintes Secrets no seu repositório do GitHub: SSH_HOST (IP público), SSH_USER (ubuntu), SSH_PRIVATE_KEY (Chave privada) e SSH_PORT (22).

Salve o arquivo .github/workflows/deploy.yml no seu repositório de código local:

YAML

name: Deploy FastAPI




on:

  push:

    branches: [ main ]




jobs:

  deploy:

    runs-on: ubuntu-latest

    steps:

      - name: Conectar via SSH e atualizar a aplicação

        uses: appleboy/ssh-action@v1.0.3

        with:

          host: ${{ secrets.SSH_HOST }}

          username: ${{ secrets.SSH_USER }}

          key: ${{ secrets.SSH_PRIVATE_KEY }}

          port: ${{ secrets.SSH_PORT }}

          script: |

            cd ~/app-fastapi

            git pull origin main

            docker compose up -d --build

            docker image prune -f

5. Validação 

Testes internos

Na instância da API, confirme que o container está ativo e respondendo aos testes locais de conectividade:

Bash

docker compose ps

curl http://localhost:8000/

curl http://localhost:8000/health

Teste externo e isolamento

A partir da sua máquina local fora da nuvem, confirme o acesso público e certifique-se de que a porta de dados (5432) está completamente bloqueada para a internet:

Bash

# Deve retornar cabeçalhos HTTP 200 OK

curl -I http://<SEU_IP_PUBLICO_VPC>:8000/




# Deve resultar em falha de conexão (Timeout), provando o isolamento do banco

nc -zv <SEU_IP_PUBLICO_VPC> 5432

6. Solução de problemas (Troubleshooting)

• API inacessível externamente (Timeout): Revise as abas de Encaminhamento de porta e Firewall do seu IP público no painel CloudStack. Certifique-se de liberar a entrada na porta 8000 direcionada à sua VM da API.
• Erro de conexão com o banco no endpoint /health: Acesse a VM do banco e confirme se o arquivo postgresql.conf está configurado para escutar o IP 10.0.2.15 e se o pg_hba.conf contém a liberação para a sub-rede 10.0.1.0/24.
• Containers reiniciando em loop: Erros na inicialização do contêiner geralmente indicam falhas na string DATABASE_URL. Inspecione a saída do terminal executando:

Bash

docker compose logs --tail=50 api