Build Ready Protocol
Antes de compilar qualquer linha de código, seu ambiente precisa estar "armado" com as ferramentas fundamentais. Este guia cobre o setup universal para Windows (PowerShell) e Linux/Docker.
Frontend (React & Vite)
O Vite proporciona o ambiente ultrarrápido para o desenvolvimento da interface moderna em React.
Backend (FastAPI & Python)
Motor de inteligência e orquestração de Agentes e LLMs, escrito em Python garantindo escalabilidade.
> Dependências Core Universais
// Instalação via Winget (Windows)
winget install --id Git.Git GitHub.cli OpenJS.NodeJS -e
> Build Frontend (React)
// Instalar Pacotes e Iniciar Vite Server
npm install ; npm run dev
> Build Backend (Python)
// Ambiente Virtual, Pip Install e Uvicorn Server
python -m venv venv ; .\venv\Scripts\activate ; pip install -r requirements.txt ; uvicorn main:app --reload
☸️ GUIA DEFINITIVO SRE: Kubernetes
Este guia serve como a base de sobrevivência e orquestração. Ele evolui do zero até os comandos de debugging extremo e arquitetura. NUNCA rode um comando complexo sem antes garantir que as dependências base estão instaladas e no PATH.
Docker: O Motor de Virtualização
O que é: Plataforma que empacota o código e suas dependências em containers padronizados.
Por que usar: Elimina o "na minha máquina funciona". O container que roda no seu PC é 100% idêntico ao que vai para a nuvem em produção. O K8s precisa do Docker (ou containerd) como motor base para instanciar as imagens.
Pod: A Unidade Fundamental
O que é: A menor unidade gerenciável do Kubernetes. Atua como uma "cápsula" que envelopa um ou mais containers Docker, gerenciando recursos, armazenamento e rede de forma isolada.
Deployment: Gestão de Estado & Escala
O que é: O maestro da resiliência do sistema. Define o estado desejado (ex: número de réplicas) e realiza o Auto-Healing (recriação automática) caso algum Pod apresente falha crítica.
Requests & Limits: Gestão de Recursos
O que é: Mecanismo de segurança que impede que um processo em falha consuma todos os recursos do host. Evita travamentos globais (OOM Kill) definindo limites rígidos de CPU e RAM para cada container.
> 0. Dependências Prévias (Obrigatórias)
Aviso: Sem isso, o Windows/Terminal vai acusar "comando não reconhecido".
- Docker Desktop: O motor base de virtualização.
- k3d ou Minikube: Ferramentas CLI que criam um Cluster Kubernetes "leve" rodando dentro do Docker, poupando a RAM do SO.
Instalação (k3d): choco install k3d - kubectl: A varinha mágica. O cliente oficial de linha de comando que conversa com o cluster K8s.
Instalação: winget install -e --id Kubernetes.kubectl - Helm: O Gerenciador de Pacotes do Kubernetes. Usado para instalar stacks complexas como o Grafana de forma automatizada.
Instalação: winget install Helm.Helm
> 1. Kubernetes: O Início (Visualização)
Use estes comandos para saber o que está acontecendo na infraestrutura.
// Verifica se o cluster e o Control Plane estão online
kubectl cluster-info ; kubectl get nodes
// Lista divisões (namespaces) e pods em execução
kubectl get namespaces ; kubectl get pods -A
> 2. Kubernetes: O Dia a Dia SRE (Execução)
Comandos para aplicar IaC e verificar os logs (Sempre use arquivos .yaml).
// Criar ou Destruir recursos via YAML Declarativo
kubectl apply -f arquivo.yaml ; kubectl delete -f arquivo.yaml
// Leitura de Logs (Streaming) e Acesso Remoto (SSH no Pod)
kubectl logs -f <nome-do-pod> ; kubectl exec -it <nome-do-pod> -- /bin/sh
> 3. Kubernetes: Comandos Complexos (Tratamento de Crise)
Para quando o Auto-Healing falha e você precisa atuar como cirurgião.
// Investigação de CrashLoopBackOff (Eventos de Erro)
kubectl describe pod <nome-do-pod>
// Port-Forward (Túnel Seguro) e Topografia de Recursos
kubectl port-forward svc/<nome-do-serviço> 8080:80 ; kubectl top pods
📊 O STACK PLG - NÍVEL ARQUITETO
A visibilidade total do sistema depende de três pilares: Métricas (Números), Logs (Texto) e Painéis (Visualização). Como instalar a tríade de observabilidade (Prometheus, Loki, Grafana) em minutos, graças ao HELM.
PROMETHEUS - Motor de Métricas
O que é: O Termômetro da infra. Especializado em séries temporais numéricas.
Por que usar: Utiliza coleta ativa (Pull) para monitorar a saúde de cada container, emitindo alertas antes que o sistema caia.
LOKI - Centralização de Logs
O que é: O gravador de caixa-preta. Otimizado para agregação de logs em larga escala.
Por que usar: Diferente de outros bancos pesados, ele indexa apenas metadados (Labels), garantindo buscas instantâneas com baixo custo de servidor.
GRAFANA - Visualização
O que é: O Painel de Controle (Dashboard) unificado da infraestrutura.
Por que usar: Conecta-se ao Prometheus e ao Loki simultaneamente, permitindo cruzar gráficos de uso de CPU com linhas de erro no código na mesma tela.
> 4.1. Adicionar os repositórios no Helm
// Sincroniza e atualiza os catálogos locais
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts ; helm repo add grafana https://grafana.github.io/helm-charts ; helm repo update
> 4.2. Instalando a artilharia no namespace 'observability'
// Criar quarto isolado e instalar Stack Prometheus & Loki
kubectl create namespace observability ; helm install prometheus prometheus-community/prometheus -n observability ; helm install loki grafana/loki-stack -n observability
// Instalar o painel visual (Grafana)
helm install grafana grafana/grafana -n observability
> 4.3. Acessando o Grafana
Como acessar a tela do Grafana se ele está preso no K8s?
// Port-forward para expor a porta 80 do cluster no seu localhost:3000
kubectl get svc -n observability ; kubectl port-forward svc/grafana 3000:80 -n observability
Git & Operational Security
O controle de versão exige rigor. Protocolos de autenticação e auditoria de segurança para garantir a integridade do código.
> Controle Remoto (GitHub CLI)
// Autenticação e Gestão de Issues/Pull Requests
gh auth login ; gh repo view --web ; gh pr list ; gh issue list
> Auditoria Sentinel (Segurança Local)
// Verificar Vazamento de Dados Sensíveis e Executar Sentinela
node scripts/sentinel_audit.js --env-only ; git ls-files .env ; git status -u
SQL Data Integrity
Integridade e performance. Auditoria de execução para garantir escalabilidade e consistência dos dados.
Análise de Performance: EXPLAIN ANALYZE
Ferramenta fundamental para entender o plano de execução do banco de dados, permitindo a otimização de índices e redução de custo computacional.
// Execução de Auditoria de Consulta
EXPLAIN ANALYZE SELECT * FROM [TABLE_NAME];
🌐 Fundamentos: Como a Web Funciona
Antes de escrever uma linha de código, entenda o mapa do território. Toda aplicação web moderna tem três camadas: o que o usuário vê (Frontend), o que processa a lógica (Backend) e onde os dados vivem (Banco de Dados).
Frontend — O que o usuário VÊ
O que é: Tudo que aparece na tela do navegador. Botões, formulários, animações, cores. É a "fachada" da aplicação.
Tecnologias principais: HTML (estrutura), CSS (estilo), JavaScript (interatividade). Frameworks modernos: React (Meta), Vue, Angular (Google).
No nosso stack: Usamos React + Vite — o ambiente de desenvolvimento mais rápido do mercado hoje.
Backend — O que o usuário NÃO vê
O que é: A "sala de máquinas". Processa as regras de negócio, autentica usuários, se comunica com o banco de dados e retorna respostas via API.
Tecnologias principais: Python (FastAPI/Django), Node.js (Express), Java (Spring), Go.
No nosso stack: Python + FastAPI — rápido, moderno e nativo para IA/LLMs.
Banco de Dados — Onde os dados VIVEM
O que é: O cofre da aplicação. Armazena tudo: usuários, pedidos, mensagens, configurações.
Tipos:
• Relacional (SQL): Dados organizados em tabelas com relações. Ex: PostgreSQL, MySQL, SQLite.
• Não-relacional (NoSQL): Dados flexíveis em documentos/JSON. Ex: MongoDB, Redis, Firebase.
Regra de ouro: SQL para dados estruturados e relacionais. NoSQL para dados flexíveis e de alta escala.
API — A ponte entre os mundos
O que é: Application Programming Interface. É o "garçom" que leva o pedido do Frontend para o Backend e traz a resposta de volta.
Padrão moderno: REST API usando HTTP (GET, POST, PUT, DELETE). O Frontend faz uma requisição, o Backend processa e retorna um JSON.
Analogia: Você (usuário) faz o pedido, o garçom (API) leva para a cozinha (Backend), que busca os ingredientes no estoque (Banco de Dados) e volta com o prato pronto.
🖥️ Windows + WSL: Do Zero ao Ambiente
Antes de qualquer comando de desenvolvimento, seu Windows precisa ser liberado para executar scripts e seu ambiente Linux (WSL) precisa estar ativo. Esta é a fundação de tudo.
Por que liberar o PowerShell?
Por padrão, o Windows bloqueia a execução de scripts externos por segurança (política Restricted). Para rodar npm, pip, scripts de automação e ferramentas de dev, você precisa mudar para RemoteSigned — que permite scripts locais e assina os externos.
O que é WSL?
Windows Subsystem for Linux. Roda um kernel Linux real dentro do Windows, sem precisar de VM ou dual-boot. Com ele você tem acesso a comandos bash, apt, curl e todo o ecossistema Linux — essencial para containers Docker e Kubernetes.
> Passo 1: Liberar PowerShell para Scripts (Admin)
// Abrir PowerShell como Administrador e executar
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
> Passo 2: Instalar WSL 2 + Ubuntu
// Instala WSL com Ubuntu (requer reinicialização)
wsl --install ; wsl --set-default-version 2
> Passo 3: Instalar Ferramentas Core (Windows)
Dependências: Winget (já incluso no Windows 10/11).
// Git + GitHub CLI + Node.js em um comando
winget install --id Git.Git GitHub.cli OpenJS.NodeJS -e
> Passo 4: Atualizar Ubuntu (dentro do WSL)
// Abrir terminal Ubuntu e atualizar pacotes
sudo apt update && sudo apt upgrade -y && sudo apt install -y curl git build-essential
🐳 Docker: Containers na Prática
Docker é a tecnologia que empacota sua aplicação e todas as suas dependências em um container isolado e portátil. Elimina o "na minha máquina funciona". Pré-requisito para Kubernetes.
Container vs Máquina Virtual
Uma VM emula um computador inteiro (SO completo, ~GBs de RAM). Um Container compartilha o kernel do SO host e isola apenas a aplicação (~MBs). Resultado: containers iniciam em segundos, são portáteis e usam uma fração dos recursos.
Dockerfile: A Receita
É um arquivo de texto com instruções passo a passo de como montar a imagem do container. Você define o SO base, instala dependências, copia o código e declara o comando de inicialização. Commitado no Git junto com o código — é IaC na essência.
> Instalação: Docker Desktop (Windows + WSL)
Dependência: WSL 2 instalado e ativo (ver seção WIN+WSL).
// Instalar Docker Desktop via Winget
winget install -e --id Docker.DockerDesktop
> Comandos Essenciais do Dia a Dia
// Ver containers rodando e todas as imagens locais
docker ps ; docker images
// Build de imagem e execução do container
docker build -t minha-app:v1 . ; docker run -d -p 8080:8080 minha-app:v1
// Logs do container e acesso interno (bash)
docker logs -f <container_id> ; docker exec -it <container_id> /bin/sh
// Subir múltiplos serviços com Docker Compose
docker compose up -d ; docker compose down
// Limpeza: remover containers parados e imagens não usadas
docker system prune -f
⚙️ CI/CD: Deploy Automático
CI/CD é o pipeline que leva seu código do repositório até a produção de forma automática, rápida e segura. Sem deploy manual, sem surpresas.
CI — Integração Contínua
O que é: A cada push no repositório, uma pipeline roda automaticamente: instala dependências, executa testes e valida o código. Se falhar, o deploy não acontece. Garante que código quebrado nunca chegue em produção.
Ferramentas: GitHub Actions, GitLab CI, CircleCI, Jenkins.
CD — Entrega Contínua
O que é: Após o CI passar, o CD automatiza o deploy para o ambiente de destino (staging ou produção). No nosso stack: push na main → Cloudflare Pages compila o frontend automaticamente em ~1 minuto.
Resultado: Zero intervenção manual para colocar uma feature no ar.
> Fluxo Git para CI/CD (Dia a Dia)
Dependências: Git instalado, repositório no GitHub, Cloudflare/Render configurado.
// Fluxo completo: stage → commit → push → pipeline dispara
git add . ; git commit -m "feat: descrição da mudança" ; git push origin main
// Ver status dos deploys via GitHub CLI
gh run list --limit 5 ; gh run watch
main em projetos com equipe. Use branches com PRs revisados. Mantenha mensagens de commit descritivas (feat:, fix:, docs:, chore:) para rastreabilidade total no histórico.
🌍 DNS: O Mapa da Internet
DNS (Domain Name System) é a agenda telefônica da internet. Traduz o nome seusite.com para o endereço IP do servidor. Mexer nele sem conhecimento causa downtime, perda de e-mails e queda no ranking do Google.
Tipos de Registros DNS
A Record: Aponta o domínio para um endereço IPv4. Ex: seusite.com → 192.168.1.1
CNAME: Alias para outro domínio. Ex: www → seusite.com
MX: Define os servidores de e-mail. Mexer errado = todos os e-mails param de chegar.
TXT: Verificações de propriedade, SPF, DKIM (anti-spam).
NS: Define quem é o servidor autoritativo do domínio. Alterar NS = downtime de até 48h.
TTL — O Tempo que Ninguém Fala
TTL (Time To Live): Define por quantos segundos o registro DNS fica em cache no mundo. TTL padrão = 3600s (1 hora). Se você tiver TTL 86400 (24h) e trocar o servidor, a mudança pode demorar até 24h para propagar globalmente.
Estratégia profissional: Antes de uma migração, reduza o TTL para 300s (5 min) com 48h de antecedência. Após migrar, aumente de volta.
⚠️ O Que Causa Downtime
Trocar NS (Nameservers): Downtime de 2 a 48 horas. Afeta TUDO: site, e-mail, subdomínios.
Alterar MX sem backup: E-mails se perdem durante a propagação.
Deletar registro A: Site sai do ar imediatamente.
Renomear domínio: Perde todo o histórico de SEO, backlinks e posicionamento no Google. Evite a todo custo.
SEO & DNS: O Que Donos de Negócio PRECISAM Saber
O Google indexa o domínio, não o servidor. Trocar o domínio ou mudar URL de páginas sem redirect 301 é equivalente a destruir anos de trabalho de SEO. Se você tem uma loja online ou SaaS com tráfego orgânico, jamais mude o domínio sem um plano detalhado de redirecionamentos e monitoramento de ranking. O impacto pode durar meses.
> Diagnóstico DNS via CLI
// Consultar registros DNS de um domínio
nslookup seudominio.com ; nslookup -type=MX seudominio.com
// Verificar propagação DNS global (WSL/Linux)
dig seudominio.com +short ; dig seudominio.com NS +short
// Testar conectividade e latência com o servidor
ping seudominio.com ; tracert seudominio.com