3 min de leitura

Início rápido

  1. Instale o PgArachne
  2. Configure o ambiente
  3. Configure segurança e auth
  4. Faça deploy atrás de proxy HTTPS

Configuração

O PgArachne carrega a configuração a partir de variáveis de ambiente ou de um arquivo.

Note: schema.sql tenta criar o papel pgarachne_admin e concedê-lo a pgarachne. Sem privilégios de superusuário, a criação é ignorada. Crie o papel e o grant manualmente se necessário.
O usuário proxy (DB_USER) deve ser membro de pgarachne e pgarachne_admin para validar e criar tokens de API.
Nota de Segurança: O PgArachne não lida com senhas do banco de dados no arquivo de configuração. Ele depende do mecanismo padrão de arquivo .pgpass do PostgreSQL (ou da variável de sistema PGPASSWORD) para autenticação.
Dica: Se o PgArachne estiver atrás de um reverse proxy, defina TRUSTED_PROXIES para resolver corretamente o IP do cliente e evitar spoofing do rate limit.
Ordem de Busca: Se nenhum arquivo de configuração for especificado via CLI, ele busca em:
  1. Diretório atual: ./pgarachne.env (Todos os SOs)
  2. Configuração do usuário:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Configuração do sistema: /etc/pgarachne/pgarachne.env (Somente Linux/macOS)

Exemplo de Configuração Mínima

É tudo o que você precisa para começar:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
JWT_SECRET=change_me_to_something_secure

Referência de Configuração

VariávelObrigatórioDescrição
Conexão com Banco de Dados
DB_HOST✓Endereço do servidor PostgreSQL (ex: localhost).
DB_PORT✓Porta do banco de dados.
DB_USER✓O usuário do banco de dados com o qual o PgArachne se conecta.
DB_SSLMODE○Modo SSL do PostgreSQL. Padrão: disable.
DB_SSLROOTCERT○Caminho do certificado raiz da CA (PEM).
DB_SSLCERT○Caminho do certificado do cliente (PEM).
DB_SSLKEY○Caminho da chave privada do cliente (PEM).
Servidor HTTP
HTTP_PORT○Porta para escutar. Padrão: 8080.
API_PREFIX○Primeiro segmento do caminho URL para todos os endpoints do banco de dados (/jsonrpc, /sse, /mcp). Padrão: db, gerando rotas como /db/:banco_de_dados/jsonrpc. Defina como api para caminhos legados. Apenas letras, dígitos, hífens e underscores são permitidos.
PID_FILE○Caminho do arquivo PID do daemon usado por -start/-stop. Padrão: cache do usuário (fallback: diretório temporário).
ALLOWED_ORIGINS○Configurações de CORS. Lista separada por vírgulas de domínios permitidos (ex: https://meuapp.com). Padrão: *.
STATIC_FILES_PATH○Caminho absoluto para servir arquivos estáticos (Explorer/Frontend).
Segurança (JWT)
JWT_SECRET✓Uma string longa e aleatória usada para assinar tokens de sessão.
JWT_EXPIRY_HOURS○Validade da sessão em horas. Padrão: 8.
LOGIN_RATE_LIMIT○Máximo de tentativas de login por janela. Padrão: 5. Use 0 para desativar.
LOGIN_RATE_WINDOW○Duração da janela do rate limit. Padrão: 1m.
O rate limit de login é por instância (em memória). Em várias instâncias, use um limitador compartilhado.
TRUSTED_PROXIES○Proxies confiáveis (IP/CIDR) para X-Forwarded-For. Separados por vírgula. Se vazio, os headers encaminhados são ignorados e o IP do cliente é obtido da conexão direta.
MAX_REQUEST_BYTES○Tamanho máximo do body em bytes. Padrão: 2097152.
METRICS_ENABLED○Habilita endpoint dedicado de métricas. Padrão: true.
METRICS_LISTEN_ADDR○Endereço do listener de métricas (host:port). Padrão: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Máximo de canais por conexão SSE. Padrão: 8.
SSE_MAX_CLIENTS○Máximo de clientes SSE simultâneos por banco de dados. Padrão: 1000.
SSE_CLIENT_BUFFER○Buffer SSE por cliente (número de mensagens). Padrão: 64.
SSE_SEND_TIMEOUT○Tempo máximo de espera ao enviar para cliente lento. Padrão: 2s.
SSE_HEARTBEAT○Intervalo de heartbeat para SSE. Padrão: 20s.
SSE_IDLE_TIMEOUT○Timeout de inatividade sem notificações. Padrão: 90s.
Logging
LOG_LEVEL○Verbosidade: DEBUG, INFO, WARN, ERROR. Padrão: INFO.
LOG_OUTPUT○Onde gravar logs: stdout ou caminho do arquivo.

Obrigatório – Opcional

Comportamento de segurança: requisições sem um header Authorization válido são rejeitadas antes de abrir conexão com o banco.

Inicie o servidor:

./pgarachne -config .env

Documentação relacionada

← Instalação Exemplo Hello World →