Configuración

5 min de lectura

Inicio rápido

  1. Instala PgArachne
  2. Configura el entorno
  3. Configura seguridad y auth
  4. Despliega detrás de proxy HTTPS

Configuración

PgArachne carga la configuración desde variables de entorno o un archivo.

Nota: schema.sql intenta crear el rol pgarachne_admin y concederlo a pgarachne. Sin privilegios de superusuario, la creación se omite. Cree el rol y el grant manualmente si es necesario.
El usuario proxy (DB_USER) debe ser miembro de pgarachne y pgarachne_admin para verificar y crear tokens de API.
Nota de Seguridad: PgArachne no maneja contraseñas de base de datos en el archivo de configuración. Confía en el mecanismo estándar de archivo .pgpass de PostgreSQL (o la variable del sistema PGPASSWORD) para la autenticación.
Consejo: Si PgArachne está detrás de un reverse proxy, configura TRUSTED_PROXIES para resolver bien la IP del cliente y evitar spoofing del rate limit.
Orden de Búsqueda: Si no se especifica ningún archivo de configuración a través de CLI, busca en:
  1. Directorio actual: ./pgarachne.env (Todos los SO)
  2. Configuración de usuario:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Configuración del sistema: /etc/pgarachne/pgarachne.env (Solo Linux/macOS)

Ejemplo de configuración mínima

Esto es todo lo necesario para comenzar:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
# Optional — enables JWT sessions (POST /db//token):
# JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Variables obligatorias: DB_HOST, DB_PORT, DB_USER.

JWT_SECRET es opcional. Configúrelo (mínimo 32 bytes; genérelo con openssl rand -hex 32) para habilitar las sesiones JWT mediante POST /{prefix}/{database}/token y los JWT emitidos externamente. Sin él, el soporte de JWT queda desactivado y los clientes se autentican con credenciales HTTP Basic (usuario y contraseña de la base de datos) o con tokens de API de larga duración.

Checklist rápida de validación

  • Si JWT está habilitado, JWT_SECRET es largo, aleatorio y no se reutiliza entre entornos.
  • DB_USER solo puede cambiar a roles esperados (verifique los grants de membresía).
  • TRUSTED_PROXIES está configurado si se ejecuta detrás de un reverse proxy.
  • LOGIN_RATE_LIMIT está habilitado para despliegues expuestos a internet.
  • METRICS_LISTEN_ADDR es privado (por ejemplo 127.0.0.1:9090).

Referencia de configuración

VariableRequeridoDescripción
Conexión a Base de Datos
DB_HOST✓Dirección del servidor PostgreSQL (ej. localhost).
DB_PORT✓Puerto de la base de datos.
DB_USER✓El usuario de base de datos con el que se conecta PgArachne.
DB_SSLMODE○Modo SSL de PostgreSQL. Por defecto: require. Establece disable explícitamente solo para desarrollo local contra un PostgreSQL sin TLS.
DB_SSLROOTCERT○Ruta al certificado raíz de CA (PEM).
DB_SSLCERT○Ruta al certificado de cliente (PEM).
DB_SSLKEY○Ruta a la clave privada del cliente (PEM).
Servidor HTTP
HTTP_PORT○Puerto para escuchar. Por defecto: 8080.
API_PREFIX○Primer segmento de ruta URL para todos los endpoints de base de datos (/jsonrpc, /file, /sse, /mcp). Por defecto: db, generando rutas como /db/:base_de_datos/jsonrpc. Solo se permiten letras, dígitos, guiones y guiones bajos.
PID_FILE○Ruta del archivo PID del demonio usado por -start/-stop. Predeterminado: caché de usuario (fallback: directorio temporal).
ALLOWED_ORIGINS○Configuración de CORS. Lista separada por comas de dominios permitidos (ej. https://miapp.com). Por defecto: sin definir — las solicitudes de origen cruzado del navegador están deshabilitadas. Establece * explícitamente para permitir cualquier origen.
STATIC_FILES_PATH○Ruta absoluta para servir archivos estáticos (Explorer/Frontend).
Seguridad (JWT & login)
JWT_SECRET○Una cadena larga y aleatoria utilizada para firmar tokens de sesión. Mínimo 32 bytes; genéralo con openssl rand -hex 32. Si no se establece, el soporte de JWT queda desactivado: el endpoint /token no está disponible y los clientes se autentican únicamente con credenciales HTTP Basic o tokens de API.
JWT_EXPIRY_HOURS○Validez de la sesión en horas (debe ser mayor que 0). Por defecto: 8.
JWT_ISSUER○Si se establece, se escribe en el claim iss y debe coincidir exactamente al validar. Vacío = sin verificación.
JWT_AUDIENCE○Si se establece, se escribe en el claim aud y debe coincidir al validar. Vacío = sin verificación.
JWT_LEEWAY○Tolerancia de reloj para exp/nbf/iat (ej. 30s). Por defecto: 30s.
LOGIN_RATE_LIMIT○Máximo de intentos de autenticación por IP de cliente y nombre de usuario por ventana. Se aplica a todos los métodos de login: cada petición a /token cuenta y, con credenciales HTTP Basic (en todos los endpoints), cuentan los intentos fallidos. Por defecto: 5. Usa 0 para desactivar.
LOGIN_RATE_LIMIT_PER_IP○Máximo de intentos de autenticación por IP de cliente entre todos los nombres de usuario, para que rotar nombres no eluda el límite. También cuenta los intentos Bearer fallidos (JWT o token de API no válidos). Por defecto: 5× LOGIN_RATE_LIMIT. Usa 0 para desactivar.
LOGIN_RATE_WINDOW○Duración de la ventana de rate limit. Por defecto: 1m.
El rate limit de login es por instancia (en memoria). En despliegues con varias instancias se requiere un limitador compartido.
TRUSTED_PROXIES○IPs/CIDR de proxies de confianza para X-Forwarded-For. Separado por comas. Si está vacío, se ignoran los headers reenviados y la IP del cliente se toma de la conexión directa.
FILE_MAX_BYTES○Tamaño total máximo sin comprimir de una respuesta /file en bytes. Por defecto: 67108864 (64 MiB).
FILE_MAX_ENTRIES○Número máximo de archivos en una respuesta /file. Por defecto: 1000.
MAX_REQUEST_BYTES○Tamaño máximo del body en bytes. Por defecto: 2097152.
MCP_SQL_ERROR_DETAIL○Incluir el mensaje de error crudo de PostgreSQL en los errores de las herramientas MCP. Los errores detallados ayudan a los agentes LLM a autocorregirse, pero pueden exponer detalles del esquema (nombres de tablas y restricciones) a los llamantes autenticados. Por defecto: false.
DIRECT_POOL_LIMIT○Número máximo de pools de conexión distintos para credenciales de Basic Auth. Por defecto: 1000.
METRICS_ENABLED○Habilita el endpoint dedicado de métricas. Predeterminado: true.
METRICS_LISTEN_ADDR○Dirección del listener de métricas (host:port). Predeterminado: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Máximo de canales por conexión SSE. Por defecto: 8.
SSE_MAX_CLIENTS○Máximo de clientes SSE simultáneos por base de datos. Por defecto: 1000.
SSE_CLIENT_BUFFER○Buffer SSE por cliente (número de mensajes). Por defecto: 64.
SSE_SEND_TIMEOUT○Tiempo máximo de espera al enviar a un cliente lento. Por defecto: 2s.
SSE_HEARTBEAT○Intervalo de heartbeat para SSE. Por defecto: 20s.
SSE_IDLE_TIMEOUT○Timeout de inactividad sin notificaciones. Por defecto: 90s.
Logging
LOG_LEVEL○Verbosidad: DEBUG, INFO, WARN, ERROR. Por defecto: INFO.
LOG_OUTPUT○Dónde escribir los logs: stdout o ruta del archivo.

Obligatorio   Opcional

Comportamiento de seguridad: las solicitudes sin un header Authorization válido se rechazan antes de abrir una conexión a la base de datos.

Inicia el servidor:

./pgarachne -config .env

Documentación relacionada

← Instalación JSON-RPC →