Infrazin: Infraestrutura Minimalista de Alta Performance

Visão Geral & Filosofia

O Infrazin nasceu com uma missão inegociável: substituir paas pesadas que consomem mais de 800 MB a 1.5 GB de memória em repouso por uma arquitetura enxuta, determinística e feita sob medida para agentes de Inteligência Artificial e desenvolvedores individuais.

Arquitetura do Core

A pilha do Infrazin é composta por 4 contêineres essenciais e altamente otimizados, orquestrados via /root/infrazin/core/docker-compose.yml na rede infrazin_net:

graph TD
    Client[Web Visitors / Apps] -->|HTTPS 443| Cloudflare[Cloudflare Edge / CDN]
    Cloudflare -->|HTTPS / DNS-01| Caddy[infrazin_caddy:443/80]
    
    subgraph "Rede Docker: infrazin_net (Bridge Interna)"
        Caddy -->|Reverse Proxy| App1[agentformlead_app:8000]
        Caddy -->|Reverse Proxy| App2[catalogozin_app:8000]
        Caddy -->|Reverse Proxy| Docs[docsinfrazin_app:80]
        Caddy -->|Reverse Proxy| Dozzle[infrazin_dozzle:8080]
        
        App1 -->|User Isolado| PG[(infrazin_postgres:5432)]
        App2 -->|DB catalogozin_prod| PG
        App2 -->|Index 1| Redis[(infrazin_redis:6379)]
    end
          

Início Rápido (Quickstart)

Conectar qualquer nova aplicação ao Infrazin leva menos de 2 minutos através de 4 passos fundamentais:

infrazin db create meunovoapp --env-file /root/projetos/meunovoapp/.env

services:
  app:
    build: .
    container_name: meunovoapp_app
    restart: always
    expose:
      - "8000"
    networks:
      - infrazin_net

networks:
  infrazin_net:
    external: true

infrazin domain add meunovoapp api.meusite.com.br meunovoapp_app:8000

cd /root/projetos/meunovoapp && docker compose up -d
infrazin doctor

A Tríade de Desenvolvimento

O desenvolvimento de software de alta performance na VPS opera através de uma sinergia perfeita entre três pilares complementares:

sequenceDiagram
    autonumber
    actor Dev as Usuário / IA
    participant CU as ClickUp (MCP)
    participant SP as Specsfy (specs/)
    participant IZ as Infrazin (VPS)
    participant GH as GitHub Actions

    Dev->>CU: 1. Consulta próxima tarefa do backlog (ex: #86b9q0t1y)
    Dev->>SP: 2. Cria spec técnica vinculada ao ID do ClickUp
    Dev->>IZ: 3. Provisiona recursos (DB, Redis, Caddy, rede infrazin_net)
    Dev->>GH: 4. Push do código com deploy automático
    Dev->>SP: 5. Transição de spec (specsfy transition ... completed)
    Dev->>CU: 6. Conclui tarefa no ClickUp com relatório técnico
          

O Contrato do Infrazin (The Contract)

O Contrato do Infrazin é a especificação formal que rege a convivência das aplicações no ecossistema. Qualquer container que cumpra este contrato torna-se automaticamente compatível com proxy, banco de dados, backups e deploy contínuo.

services:
  app:
    build: .
    image: meunome_app:latest
    container_name: meunome_app
    restart: always
    
    # ⚠️ REGRA DE OURO: NUNCA exponha portas no formato "8000:8000" para o host.
    # O Caddy acessa o serviço diretamente pelo nome do container na rede interna!
    expose:
      - "8000"

    env_file:
      - .env

    volumes:
      - ./data:/app/data
      - ./app/static/uploads:/app/app/static/uploads

    networks:
      - infrazin_net

networks:
  infrazin_net:
    external: true

Referência do CLI (`infrazin`)

O executável infrazin é uma ferramenta Python de alto nível instalada em /usr/local/bin/infrazin. Abaixo está a relação de todos os comandos disponíveis:

infrazin doctor

infrazin status

PostgreSQL & Redis Central

Para garantir máxima densidade de projetos na VPS e evitar o consumo excessivo de múltiplos motores de banco de dados, o Infrazin adota um modelo centralizado rigorosamente blindado.

Caddy, Cloudflare & SSL

O roteamento de entrada é operado pelo Caddy compilado com o módulo oficial caddy-dns/cloudflare. Essa integração resolve automaticamente desafios DNS-01 diretamente nos servidores DNS da Cloudflare.

# Configuração Infrazin para agentformlead
agentformlead.fulcroalavanc.com.br {
    import cloudflare_tls
    import security_headers
    import compression

    reverse_proxy agentformlead_app:8000
}

CI/CD GitHub Actions & Rollback

Conforme estabelecido no ADR-001 e ADR-021, cada projeto possui um workflow desacoplado no GitHub Actions. Ao fazer push na branch main (ou saas), o runner conecta na VPS via SSH, puxa as alterações, recria os containers e valida a saúde do endpoint.

name: Deploy to Infrazin

on:
  push:
    branches: [ main, saas ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy via SSH
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.INFRAZIN_HOST }}
          username: ${{ secrets.INFRAZIN_USER }}
          key: ${{ secrets.INFRAZIN_SSH_KEY }}
          script: |
            cd /root/projetos/${{ github.event.repository.name }}
            git pull origin ${{ github.ref_name }}
            docker compose build
            docker compose up -d
            
            # Healthcheck de 10 segundos com Rollback
            sleep 5
            CONTAINER_NAME="${{ github.event.repository.name }}_app"
            STATUS=$(docker inspect -f '{{.State.Status}}' $CONTAINER_NAME 2>/dev/null)
            if [ "$STATUS" != "running" ]; then
              echo "Deploy falhou! Executando Rollback..."
              git checkout HEAD~1
              docker compose up -d
              exit 1
            fi
            echo "Deploy concluído com sucesso!"

Observabilidade & Logs

O Infrazin adota o Dozzle v11 para acompanhamento visual de logs em tempo real sem a necessidade de manter conexões de terminal abertas.

Registros de Decisão de Arquitetura (ADR)

Todas as decisões de design foram debatidas e formalizadas para garantir a longevidade e determinismo da infraestrutura:

Troubleshooting & FAQ

ufw status
ufw allow 8080/tcp comment 'Infrazin Dozzle'

docker logs --tail=100 -f <nome_do_container>

infrazin doctor