Referencia de configuración

La referencia completa para configurar una instancia autoalojada. La guía de despliegue te lleva a aplicar estos ajustes en orden; esta página es a la que vuelves para el nombre y el significado exactos de cada ajuste.

Variables de entorno

Establécelas como variables de entorno (o mediante un gestor de secretos en producción).

Variable	Obligatoria	Propósito
KEYRIGHT_DB	sí	Cadena de conexión Npgsql (consulta Base de datos). Compose la construye a partir de POSTGRES_PASSWORD para la BD incluida.
KEYRIGHT_ADMIN_TOKEN	sí	Tu credencial de proveedor/administración, que protege cada llamada /admin/*. La ruta de runtime del cliente (/v1/*) nunca la necesita. Trátala como una contraseña de root — si no se establece, toda la superficie de administración devuelve 401.
KEYRIGHT_KEK	sí	Clave de cifrado de claves de 32 bytes en Base64 que cifra tus claves de firma en reposo. El servicio se niega a arrancar sin ella en Producción.
KEYRIGHT_SELF_LICENSE / _FILE	sí	Tu licencia o clave de prueba de Keyright (Licenciamiento) — JSON en línea, o una ruta a un archivo. Necesaria para ejecutar.
KEYRIGHT_SIGNING_KEY	recomendada	Clave privada RSA PKCS#8 en Base64 que firma los leases offline y los bloques de crédito aislados. Las aplicaciones de tus clientes integran la clave pública correspondiente. Si no se establece, se genera una clave por inquilino en la BD.
KEYRIGHT_SELF_LICENSE_GRACE_DAYS	opcional	Ventana de gracia de solo lectura de pago tras el vencimiento (por defecto 15).
KEYRIGHT_LEASE_TTL_DAYS	opcional	Duración del lease en línea (por defecto 14).
KEYRIGHT_PUBLIC_URL	opcional	Origen externo https://… del panel/portal, para que los enlaces se resuelvan correctamente detrás de un proxy.
KEYRIGHT_CRON_SECRET	opcional	Protege los endpoints del planificador externo (consulta Operaciones → Tareas programadas).
KEYRIGHT_BRAND_NAME / _COMPANY / _LOGO_URL / _COLOR / _SUPPORT_URL	opcional	Marca blanca del panel/portal — una característica Enterprise (se aplica solo cuando tu licencia otorga whitelabel; de lo contrario, la marca neutra de Keyright). Consulta Marca blanca.
KEYRIGHT_SSO_ISSUER / _AUDIENCE / _PUBLIC_KEY / _AUTHORITY	opcional	SSO del panel (SAML/OIDC) — una característica Enterprise (activa solo cuando tu licencia otorga sso).
KEYRIGHT_GEOIP_URL	opcional	Búsqueda de ubicación del equipo; déjala vacía para desactivarla en ejecuciones aisladas.
KEYRIGHT_PORT	opcional	Puerto del host para el archivo Compose incluido (por defecto 8080).
KEYRIGHT_PLATFORM_TOKEN	déjala sin establecer	El modo multi-inquilino / operador es una capacidad licenciada, exclusiva del modo gestionado. Este token solo se respeta cuando la autolicencia otorga un derecho operator — que las licencias autoalojadas nunca llevan — así que en una instancia autoalojada no tiene ningún efecto: la instancia siempre es de un solo inquilino y permanece totalmente sujeta a licencia. La multi-inquilinaria es exclusiva del servicio gestionado (SaaS) de Keyright.

Generar los secretos

openssl rand -hex 24                                                            # KEYRIGHT_ADMIN_TOKEN
openssl rand -base64 32                                                         # KEYRIGHT_KEK (decodes to 32 bytes)
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform DER | base64 -w0   # KEYRIGHT_SIGNING_KEY

(En macOS/BSD, base64 no tiene -w0; usa ... -outform DER | base64 | tr -d '\n'.) Tu KEYRIGHT_KEK y tu KEYRIGHT_SIGNING_KEY son tuyas — las generas tú, nosotros nunca las vemos. Haz copia de seguridad de ellas por separado y de forma segura: sin la KEK, las claves de firma cifradas en tu base de datos no pueden recuperarse.

Base de datos

Tú proporcionas un servidor PostgreSQL y una base de datos vacía; Keyright construye el esquema por sí mismo en el primer arranque. Nunca importas un esquema ni ejecutas SQL a mano — las migraciones están compiladas en la imagen y se ejecutan automáticamente (db.Database.Migrate()), de modo que el primer arranque y cada actualización son un solo paso.

Crear la base de datos y el rol

CREATE DATABASE keyright ENCODING 'UTF8' TEMPLATE template0;
CREATE ROLE keyright_app LOGIN PASSWORD 'a-strong-password';
ALTER DATABASE keyright OWNER TO keyright_app;   -- simplest: the app role owns its database

El rol de la aplicación debe poder ejecutar DDL (CREATE/ALTER/DROP), porque Keyright aplica migraciones de EF Core al arrancar — el primer arranque crea cada tabla y siembra el inquilino por defecto; las actualizaciones aplican solo las migraciones nuevas. Hacer que el rol sea el propietario de la base de datos es la configuración correcta más simple. En PostgreSQL 15+, si el rol no es el propietario, añade también GRANT ALL ON SCHEMA public TO keyright_app;.

Algunos proveedores gestionados (Azure Database for PostgreSQL Flexible Server, Cloud SQL) no te dejan ejecutar CREATE DATABASE directamente — crea la base de datos vacía y el rol desde su consola/CLI en su lugar, y luego otorga permisos como se indica arriba. AWS RDS/Aurora, Google Cloud SQL, Azure, Neon, Supabase, etc. funcionan todos.

Cadena de conexión (KEYRIGHT_DB)

Formato Npgsql; exige TLS contra cualquier Postgres gestionado:

Host=db.internal.example.com;Port=5432;Database=keyright;Username=keyright_app;Password=...;SSL Mode=Require;Trust Server Certificate=true

Usa Trust Server Certificate=true solo si no validas la CA del servidor; prefiere SSL Mode=VerifyFull con una CA de confianza en producción.

Postgres incluido (solo evaluación)

docker compose y el chart de Helm (postgres.enabled=true) pueden arrancar un postgres:16 por ti, con la base de datos y el rol precreados y un volumen persistente. Está bien para evaluación e instalaciones pequeñas de un solo nodo; para producción ejecuta un Postgres gestionado o HA y apunta KEYRIGHT_DB a él.

Marca blanca del panel y el portal (Enterprise)

Establece las variables de marca y reinicia. Se aplican solo cuando tu licencia otorga whitelabel (Enterprise); en Standard o una licencia caducada se usa la marca neutra Keyright y estas se ignoran. No hay un conmutador “Settings” en el panel para esto en autoalojamiento — la marca es configuración, no un ajuste almacenado.

KEYRIGHT_BRAND_NAME=Acme Licensing                     # replaces "Keyright" in the dashboard/portal + emails
KEYRIGHT_BRAND_COMPANY=Acme GmbH                       # footer / legal line
KEYRIGHT_BRAND_LOGO_URL=https://cdn.acme.example/logo.svg   # absolute https URL to a logo (SVG/PNG); omit for the default mark
KEYRIGHT_BRAND_COLOR=#2f63f6                           # accent colour as a hex #RRGGBB
KEYRIGHT_BRAND_SUPPORT_URL=https://acme.example/support    # "Support" link target

Confirma que se aplicó con GET <base>/branding (devuelve el nombre/empresa/logo/color en vivo).

Valores de Kubernetes (Helm)

El chart en deploy/helm/keyright/ lee estos valores. La guía de despliegue tiene los comandos helm upgrade --install completos; los parámetros que establecerás con más frecuencia:

Valor	Propósito
image.repository / image.tag	Imagen + versión. Sin image.tag se usa por defecto el appVersion del chart; fíjalo (p. ej. --set image.tag=2.2.2) para despliegues reproducibles.
secrets.adminToken / secrets.kek	Obligatorios — el chart se niega a renderizar sin ellos. Pásalos con --set-string.
secrets.selfLicense	Tu licencia. Pásala con --set-file secrets.selfLicense=license.json — nunca con --set-string (las comas del JSON rompen el parser).
postgres.enabled	true (por defecto) ejecuta un Postgres incluido dentro del clúster para evaluación; ponlo en false para producción y proporciona externalDatabase.connectionString.
postgres.image	Sustituye la imagen de BD incluida, p. ej. --set postgres.image=<registry>/postgres:16 para evitar los límites de descarga de Docker Hub o en un clúster restringido.
externalDatabase.connectionString	Tu KEYRIGHT_DB cuando postgres.enabled=false. Pásala con --set-string (contiene comas).
replicaCount	Número de nodos de aplicación sin estado (2+ para HA — no se necesita afinidad de sesión).
brand.name / .company / .color / .logoUrl / .supportUrl	Marca blanca (Enterprise). Pásalos con --set-string.
ingress.*, resources.*	Host/TLS del ingress y CPU/memoria por pod. Consulta values.yaml para cada parámetro.

La aplicación ejecuta sus migraciones de base de datos al arrancar, así que la base de datos debe estar accesible cuando arranca el pod — una BD inaccesible (host/credenciales incorrectos, sin ruta de red, regla de firewall ausente) deja el pod en CrashLoopBackOff con un error de “connection” de Npgsql, no en un pod no-listo. Confirma el DNS/egreso a tu BD antes de desplegar. GET /health es liveness; GET /health/ready también comprueba la conectividad de la BD una vez en marcha.

Llega al servicio sin un ingress mediante un port-forward. El servicio se llama <release>-keyright — con el release keyright eso se resuelve a keyright-keyright:

kubectl port-forward -n keyright svc/keyright-keyright 8080:8080