4 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.

Note: schema.sql intenta crear el rol pgarachne_admin y concederlo a pgarachne. Sin privilegios de superusuario, la creación se omite. Crea 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 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 que necesitas para empezar:

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

Checklist rápida de validación

  • JWT_SECRET es largo, aleatorio y no se reutiliza entre entornos.
  • DB_USER solo puede cambiar a roles esperados (revisa los grants de membresía).
  • TRUSTED_PROXIES está configurado si ejecutas 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: disable.
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, /sse, /mcp). Por defecto: db, generando rutas como /db/:base_de_datos/jsonrpc. Usa api para rutas legacy. 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: *.
STATIC_FILES_PATH○Ruta absoluta para servir archivos estáticos (Explorer/Frontend).
Seguridad (JWT)
JWT_SECRET✓Una cadena larga y aleatoria utilizada para firmar tokens de sesión.
JWT_EXPIRY_HOURS○Validez de la sesión en horas. Por defecto: 8.
LOGIN_RATE_LIMIT○Máximo de intentos de login por ventana. Por defecto: 5. 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.
MAX_REQUEST_BYTES○Tamaño máximo del body en bytes. Por defecto: 2097152.
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

Ver también

Documentación relacionada

← Instalación Ejemplo Hello World →