Référence de configuration

La référence complète pour configurer une instance auto-hébergée. Le guide de déploiement vous guide pour appliquer ces paramètres dans l’ordre ; cette page est celle à laquelle vous revenez pour le nom et la signification exacts de chaque paramètre.

Variables d’environnement

Définissez-les comme variables d’environnement (ou via un gestionnaire de secrets en production).

Variable	Requise	Rôle
KEYRIGHT_DB	oui	Chaîne de connexion Npgsql (voir Base de données). Compose la construit à partir de POSTGRES_PASSWORD pour la base embarquée.
KEYRIGHT_ADMIN_TOKEN	oui	Votre identifiant éditeur/admin, qui protège chaque appel /admin/*. Le chemin runtime client (/v1/*) n’en a jamais besoin. Traitez-le comme un mot de passe root — s’il n’est pas défini, toute la surface d’administration répond 401.
KEYRIGHT_KEK	oui	Clé de chiffrement de clés (key-encryption-key) de 32 octets en Base64 qui chiffre vos clés de signature au repos. Le service refuse de démarrer sans elle en Production.
KEYRIGHT_SELF_LICENSE / _FILE	oui	Votre licence Keyright ou clé d’essai (Licence) — JSON en ligne, ou chemin vers un fichier. Requise pour démarrer.
KEYRIGHT_SIGNING_KEY	recommandée	Clé privée RSA PKCS#8 en Base64 qui signe les leases hors ligne et les blocs de crédits isolés (air-gapped). Les applications de vos clients embarquent la clé publique correspondante. Si elle n’est pas définie, une clé par tenant est générée dans la base.
KEYRIGHT_SELF_LICENSE_GRACE_DAYS	facultative	Fenêtre de grâce payante en lecture seule après expiration (par défaut 15).
KEYRIGHT_LEASE_TTL_DAYS	facultative	Durée de vie d’une lease en ligne (par défaut 14).
KEYRIGHT_PUBLIC_URL	facultative	Origine externe https://… du tableau de bord/portail, pour que les liens se résolvent correctement derrière un proxy.
KEYRIGHT_CRON_SECRET	facultative	Protège les endpoints du planificateur externe (voir Exploitation → Tâches planifiées).
KEYRIGHT_BRAND_NAME / _COMPANY / _LOGO_URL / _COLOR / _SUPPORT_URL	facultative	Marque blanche du tableau de bord/portail — une fonctionnalité Enterprise (appliquée seulement quand votre licence accorde whitelabel ; sinon, la marque neutre Keyright). Voir Marque blanche.
KEYRIGHT_SSO_ISSUER / _AUDIENCE / _PUBLIC_KEY / _AUTHORITY	facultative	SSO du tableau de bord (SAML/OIDC) — une fonctionnalité Enterprise (active seulement quand votre licence accorde sso).
KEYRIGHT_GEOIP_URL	facultative	Recherche de la localisation des machines ; définissez-la vide pour la désactiver dans les exécutions isolées (air-gapped).
KEYRIGHT_PORT	facultative	Port hôte pour le fichier Compose fourni (par défaut 8080).
KEYRIGHT_PLATFORM_TOKEN	ne pas définir	Le mode multi-tenant / opérateur est une capacité sous licence, réservée au service managé. Ce jeton n’est honoré que lorsque l’auto-licence accorde un droit operator — que les licences auto-hébergées ne portent jamais — donc sur une instance auto-hébergée il n’a aucun effet : l’instance est toujours mono-tenant et reste entièrement soumise à la licence. Le multi-tenant est exclusif au service managé (SaaS) de Keyright.

Générer les secrets

openssl rand -hex 24                                                            # KEYRIGHT_ADMIN_TOKEN
openssl rand -base64 32                                                         # KEYRIGHT_KEK (se décode en 32 octets)
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform DER | base64 -w0   # KEYRIGHT_SIGNING_KEY

(Sur macOS/BSD, base64 n’a pas d’option -w0 ; utilisez ... -outform DER | base64 | tr -d '\n'.) Vos KEYRIGHT_KEK et KEYRIGHT_SIGNING_KEY sont à vous — vous les générez, nous ne les voyons jamais. Sauvegardez-les séparément et de manière sécurisée : sans la KEK, les clés de signature chiffrées dans votre base de données ne peuvent pas être récupérées.

Base de données

Vous fournissez un serveur PostgreSQL et une base de données vide ; Keyright construit lui-même le schéma au premier démarrage. Vous n’importez jamais de schéma et n’exécutez jamais de SQL à la main — les migrations sont compilées dans l’image et s’exécutent automatiquement (db.Database.Migrate()), de sorte que le premier démarrage et chaque mise à niveau tiennent en une seule étape.

Créer la base de données et le rôle

CREATE DATABASE keyright ENCODING 'UTF8' TEMPLATE template0;
CREATE ROLE keyright_app LOGIN PASSWORD 'a-strong-password';
ALTER DATABASE keyright OWNER TO keyright_app;   -- le plus simple : le rôle applicatif est propriétaire de sa base

Le rôle applicatif doit pouvoir exécuter du DDL (CREATE/ALTER/DROP), car Keyright applique les migrations EF Core au démarrage — le premier démarrage crée chaque table et initialise le tenant par défaut ; les mises à niveau n’appliquent que les nouvelles migrations. Faire du rôle le propriétaire de la base est la configuration correcte la plus simple. Sur PostgreSQL 15+, si le rôle n’est pas le propriétaire, ajoutez aussi GRANT ALL ON SCHEMA public TO keyright_app;.

Certains fournisseurs managés (Azure Database for PostgreSQL Flexible Server, Cloud SQL) ne vous laissent pas exécuter CREATE DATABASE directement — créez plutôt la base vide et le rôle depuis leur console/CLI, puis accordez les droits comme ci-dessus. AWS RDS/Aurora, Google Cloud SQL, Azure, Neon, Supabase, etc. fonctionnent tous.

Chaîne de connexion (KEYRIGHT_DB)

Format Npgsql ; exigez TLS face à tout Postgres managé :

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

N’utilisez Trust Server Certificate=true que si vous ne validez pas la CA du serveur ; préférez SSL Mode=VerifyFull avec une CA de confiance en production.

Postgres embarqué (évaluation uniquement)

docker compose et le chart Helm (postgres.enabled=true) peuvent démarrer un postgres:16 pour vous, avec la base de données et le rôle pré-créés et un volume persistant. Convient pour l’évaluation et les petites installations à nœud unique ; en production, exécutez un Postgres managé ou HA et pointez KEYRIGHT_DB vers lui.

Marque blanche du tableau de bord et du portail (Enterprise)

Définissez les variables de marque et redémarrez. Elles ne s’appliquent que lorsque votre licence accorde whitelabel (Enterprise) ; sous Standard ou avec une licence échue, la marque neutre Keyright est utilisée et ces variables sont ignorées. Il n’y a pas d’interrupteur « Settings » dans le tableau de bord pour cela en auto-hébergement — la marque relève de la configuration, pas d’un réglage stocké.

KEYRIGHT_BRAND_NAME=Acme Licensing                     # remplace "Keyright" dans le tableau de bord/portail + les e-mails
KEYRIGHT_BRAND_COMPANY=Acme GmbH                       # pied de page / mention légale
KEYRIGHT_BRAND_LOGO_URL=https://cdn.acme.example/logo.svg   # URL https absolue vers un logo (SVG/PNG) ; omettez pour le logo par défaut
KEYRIGHT_BRAND_COLOR=#2f63f6                           # couleur d'accentuation en hexadécimal #RRGGBB
KEYRIGHT_BRAND_SUPPORT_URL=https://acme.example/support    # cible du lien "Support"

Confirmez l’application avec GET <base>/branding (renvoie le nom/la société/le logo/la couleur en vigueur).

Valeurs Kubernetes (Helm)

Le chart dans deploy/helm/keyright/ lit ces valeurs. Le guide de déploiement contient les commandes helm upgrade --install complètes ; les réglages que vous définirez le plus souvent :

Valeur	Rôle
image.repository / image.tag	Image + version. Non défini, image.tag prend par défaut l’appVersion du chart ; épinglez-le (p. ex. --set image.tag=2.2.2) pour des déploiements reproductibles.
secrets.adminToken / secrets.kek	Obligatoires — le chart refuse de se rendre sans eux. Passez-les avec --set-string.
secrets.selfLicense	Votre licence. Passez-la avec --set-file secrets.selfLicense=license.json — jamais avec --set-string (les virgules du JSON cassent l’analyseur).
postgres.enabled	true (par défaut) exécute un Postgres embarqué dans le cluster pour l’évaluation ; mettez false en production et fournissez externalDatabase.connectionString.
postgres.image	Remplace l’image de base de données embarquée, p. ex. --set postgres.image=<registry>/postgres:16 pour éviter les limites de téléchargement Docker Hub ou dans un cluster verrouillé.
externalDatabase.connectionString	Votre KEYRIGHT_DB quand postgres.enabled=false. Passez-la avec --set-string (contient des virgules).
replicaCount	Nombre de nœuds d’application sans état (2+ pour la HA — aucune affinité de session nécessaire).
brand.name / .company / .color / .logoUrl / .supportUrl	Marque blanche (Enterprise). Passez-les avec --set-string.
ingress.*, resources.*	Hôte/TLS de l’ingress et CPU/mémoire par pod. Voir values.yaml pour chaque réglage.

L’application exécute ses migrations de base de données au démarrage, la base doit donc être joignable au démarrage du pod — une base injoignable (hôte/identifiants incorrects, absence de chemin réseau, règle de pare-feu manquante) met le pod en CrashLoopBackOff avec une erreur « connection » Npgsql, et non en pod non prêt. Confirmez le DNS/la sortie réseau vers votre base avant de déployer. GET /health est la sonde de vivacité (liveness) ; GET /health/ready vérifie aussi la connectivité à la base une fois en marche.

Accédez au service sans ingress via un port-forward. Le service se nomme <release>-keyright — avec la release keyright, cela donne keyright-keyright :

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