# Configuración de Devkron Edge `dkle` usa dos tipos de archivo JSON: - **`dkle.json`**: el servidor (por dónde escucha, certificados, proxies de confianza). Uno por instalación. Se lee al arrancar: un cambio requiere reiniciar. - **`_config/.dkle.json`**: cada sitio (sus secretos, límites, destinos permitidos, rutas locales, errores). Uno por sitio, opcional. **Se recarga en caliente**: el cambio aplica a la siguiente petición. ## dkle.json ```json { "http": { "listen": [":80"], "redirect_https": true }, "https": { "listen": [":443"], "acme": { "email": "infra@ejemplo.com" } }, "fastcgi": null, "web": "web", "config_dir": "_config", "trusted_proxies": [], "health": { "path": "/_health", "local_only": true } } ``` | Llave | Qué hace | Por omisión | |---|---|---| | `http.listen` | Direcciones donde escucha HTTP: `":8080"`, `"127.0.0.1:8080"`, `"[::1]:8080"` | — | | `http.redirect_https` | Redirige a HTTPS (301) las peticiones HTTP de los hosts que tienen sitio; otro host recibe 404 | `false` | | `https.listen` | Direcciones donde escucha HTTPS | — | | `https.acme` | Certificados automáticos de Let's Encrypt (ver abajo) | — | | `https.cert_dir` | Carpeta con certificados que pone otra capa (ver abajo) | — | | `fastcgi.listen` | Direcciones FastCGI (`"127.0.0.1:9100"` o `"unix:/run/dkle/dkle.sock"`), para ponerlo detrás de nginx o IIS | — | | `fastcgi.unix_socket` | Ruta de un socket Unix FastCGI | — | | `fastcgi.socket_mode` | Permisos del socket Unix, en octal | `"0660"` | | `web` | Carpeta de los sitios | `"web"` | | `config_dir` | Carpeta de los `.dkle.json` | `"_config"` | | `trusted_proxies` | IP o redes (CIDR) de los proxies de confianza: solo de ellas se aceptan `X-Forwarded-For`, `X-Forwarded-Proto` y `X-Real-IP` | `[]` (ninguno) | | `default_site` | Sitio que atiende un host desconocido (sin él, 404) | — | | `log.requests` | Una línea de bitácora por petición | `true` | | `health` | Ruta de estado (ver abajo); sin la sección está apagada | apagada | `http`, `https` y `fastcgi` son opcionales y se combinan: el mismo proceso puede atender HTTPS directo y FastCGI a la vez. Una llave desconocida en `dkle.json` es un error al arrancar (para que una errata no pase inadvertida). ### HTTPS con Let's Encrypt ```json "https": { "listen": [":443"], "acme": { "email": "infra@ejemplo.com", "cache_dir": "_acme" } } ``` `dkle` pide, guarda y renueva solo el certificado de cada host que tiene sitio (o alias). Hace falta que el host apunte por DNS al servidor y que `dkle` atienda también HTTP en el puerto 80 (el desafío de Let's Encrypt llega por ahí); con `"redirect_https": true` lo demás se redirige a HTTPS. Un host que no es de ningún sitio no obtiene certificado. | Llave | Qué hace | |---|---| | `email` | Correo de la cuenta de Let's Encrypt (avisos de caducidad) | | `cache_dir` | Dónde se guardan las llaves y certificados; por omisión `_acme` junto a `dkle.json`. Respáldela y protéjala: contiene llaves privadas | | `directory_url` | Otro servidor ACME. Para probar sin gastar el cupo de Let's Encrypt, use su entorno de pruebas: `"https://acme-staging-v02.api.letsencrypt.org/directory"` | ### HTTPS con certificados propios ```json "https": { "listen": [":443"], "cert_dir": "/etc/dkle/certs" } ``` Los certificados los pone otra capa (certbot, la herramienta de su proveedor, un certificado comprado). `dkle` elige el certificado por el nombre del host (SNI) y los vuelve a leer cuando cambian: | Host | Archivos que busca en `cert_dir` | |---|---| | `api.ejemplo.com` | `api.ejemplo.com.crt` y `api.ejemplo.com.key`, o `api.ejemplo.com/fullchain.pem` y `api.ejemplo.com/privkey.pem` (estilo certbot) | | Comodín `*.ejemplo.com` | `_.ejemplo.com.crt` y `_.ejemplo.com.key` (o la carpeta `_.ejemplo.com/`) | | Sin nombre (sin SNI) | `default.crt` y `default.key` | ### Ruta de estado ```json "health": { "path": "/_health", "local_only": true } ``` Responde con cualquier `Host`, antes que los sitios: ```json {"activo_s":3600,"estado":"ok","sitios":4,"sitios_config_invalida":0,"version":"2.0.1"} ``` `estado` es `"degradado"` si algún sitio tiene su configuración inválida. Con `local_only` (por omisión `true`) solo responde a conexiones que vienen de `127.0.0.1` o `::1`; las demás siguen el camino normal (normalmente, 404). ## _config/<host>.dkle.json Un archivo por sitio, con el nombre del host: `_config/conectores.ejemplo.com.dkle.json` configura `web/conectores.ejemplo.com/`. Si no existe, el sitio funciona con los valores por omisión. ```json { "aliases": ["puente.ejemplo.com"], "app": { "erp_url": "https://erp.cliente.com/api", "erp_usuario": "conector", "zona": "America/Mexico_City" }, "env": ["ERP_CLAVE", "TIENDA_SECRETO"], "outbound": ["erp.cliente.com", "*.myshopify.com"], "local_only": ["/tareas/*"], "limits": { "timeout_ms": 20000, "max_body_kb": 1024, "max_concurrent": 20 }, "errors": { "404": "errores/404.dkl", "500": "errores/500.dkl" }, "debug": false } ``` | Llave | Qué hace | |---|---| | `aliases` | Otros hosts que atiende el mismo sitio | | `app` | Configuración del conector, la que lee `config.get("erp_url")`. Se permiten registros anidados: `config.get("erp/url")` | | `env` | Variables de entorno del proceso que el sitio puede leer con `env.get`. Las que no estén en la lista no existen para el sitio | | `outbound` | Destinos a los que el sitio puede llamar con `http.*` (ver abajo). Sin la llave, o con `["*"]`, la salida es abierta | | `local_only` | Rutas que solo responden a llamadas desde `127.0.0.1` o `::1` (tareas, administración); las demás reciben 403. `*` vale por cualquier texto | | `limits` | Límites del sitio (ver abajo) | | `errors` | Programas propios para responder 404 y 500, relativos a la carpeta del sitio | | `debug` | `true` incluye el detalle del error en las respuestas 500. Solo para desarrollo | ### Secretos: en app o en el entorno Un secreto puede ir de dos formas: - **En `app`**: lo más simple. `_config/` está fuera de `web/` y nunca se entrega por HTTP, pero el archivo queda en disco: protéjalo con permisos (`chmod 600`, dueño el usuario del servicio). - **En una variable de entorno** autorizada en `env`: el valor no queda en la configuración del sitio; lo pone el servicio (`EnvironmentFile` de systemd, variables del sistema en Windows, el gestor de secretos de su plataforma). En los dos casos, cada sitio solo ve lo suyo: un sitio no puede leer la configuración ni las variables autorizadas de otro. ### Límites | Llave | Qué limita | Por omisión | Al excederse | |---|---|---|---| | `timeout_ms` | Tiempo máximo de una ejecución (incluye las llamadas salientes) | 30 000 | La ejecución se cancela y responde 500 «tiempo de ejecución agotado» | | `max_body_kb` | Tamaño del cuerpo de la petición | 10 240 | 413 | | `max_response_kb` | Tamaño de cada respuesta que el sitio **recibe** con `http.*` | 10 240 | La llamada falla con error y `http.status()` queda en 0 | | `max_concurrent` | Peticiones del sitio que se atienden a la vez | 64 | Las demás esperan un lugar hasta `timeout_ms`; después, 503 | | `max_cache_mb` | Memoria de la caché del sitio (`cache.*`) | 64 | Se descartan primero las llaves más próximas a caducar y luego las más antiguas | | `max_call_depth` | Funciones DKL anidadas (protege de una recursión sin fin) | 3 000 | La llamada falla con un error manejable; sin manejar, 500 | Los límites son por sitio: un conector saturado o lento no afecta a los demás. ### Destinos permitidos (outbound) | Patrón | Permite | |---|---| | `"api.ejemplo.com"` | Ese host, en cualquier puerto | | `"api.ejemplo.com:8443"` | Ese host, solo en ese puerto | | `"*.ejemplo.com"` | Cualquier subdominio (`a.ejemplo.com`, `b.c.ejemplo.com`), no `ejemplo.com` mismo: agréguelo aparte si lo necesita | | `"*"` | Cualquier destino | Una llamada a un destino no permitido falla sin salir del servidor: ``` http.get_json: destino no permitido por outbound del sitio (api.otro-dominio.com:443) ``` ### Errores propios Por omisión, 404 y 500 responden JSON con el identificador de la petición (el mismo de la bitácora y del encabezado `X-Request-Id`): ```json {"error":"no encontrado","id":"e45fd6b9c37741095d0cfddc","status":404} {"error":"error interno","id":"e6d9a67c15c14f1f42266d4b","status":500} ``` Con `errors`, el sitio responde con sus propios programas. Corren con el `@http_context` de la misma petición y `response/http_status` ya puesto; en un 500, `last_error` y `last_error_code` vienen en la raíz de `@http_context`, como en el controlador FastCGI de Devkron 2.0. ### Archivo inválido Si el archivo no es un objeto JSON, o una llave conocida tiene un tipo equivocado (`local_only` que no es lista de cadenas, un límite que no es un número mayor que 0, `debug` que no es lógico…), `dkle` no atiende el sitio con valores relajados: - Si ya tenía una versión válida, la conserva y lo avisa en la bitácora. - Si no, el sitio responde **503** con `Retry-After` hasta que se corrija, y `/_health` reporta `"degradado"`. Las llaves desconocidas no invalidan el archivo; `dkle check` las avisa.