Guide de déploiement (pas à pas)

Voici le guide linéaire, « faites ceci puis cela », qui mène à une instance en marche. Il suppose que vous avez parcouru la vue d’ensemble de l’architecture. Chaque paramètre qu’il touche dispose d’une référence complète dans Configuration ; quand une étape demande plus de profondeur, elle y renvoie.

À la fin, vous disposerez d’une instance Keyright sous licence répondant sur /health, d’un tableau de bord auquel vous êtes connecté, et de l’URL de base exacte vers laquelle le SDK de votre produit pointera.

Étape 0 — Vérifier les prérequis

• Un runtime de conteneurs (recommandé) : Docker 24+ avec Compose v2, ou Kubernetes 1.24+ avec Helm 3. Ou Windows/IIS avec le .NET 8 Hosting Bundle (étape 4C, sans conteneurs).
• PostgreSQL 14+ (16 recommandé), UTF-8. Pour une première évaluation, vous pouvez laisser le bundle en démarrer un pour vous (étape 3) ; en production, préparez votre propre Postgres managé/HA.
• Une licence Keyright ou une clé d’essai fournie par Delta1 — requise pour démarrer. Contactez le service commercial pour un essai Enterprise de 30 jours ou une licence payante Standard/Enterprise. Enregistrez la clé que vous recevez sous le nom license.json.
• openssl sur la machine depuis laquelle vous exécutez ces étapes (pour générer les secrets à l’étape 2).

Étape 1 — Obtenir le kit de déploiement

L’image de conteneur est publique — récupérez-la sans authentification (épinglez la version pour une installation reproductible) :

docker pull ghcr.io/delta1-labs/keyright:2.2.2     # ou :latest

Le kit de déploiement — les fichiers de configuration auxquels le reste de ce guide fait référence — vous est envoyé par Delta1 avec votre licence (ou sur demande auprès du service commercial). Il contient :

• deploy/docker-compose.yml + deploy/.env.example (Docker Compose)
• deploy/helm/keyright/ (Kubernetes / Helm)
• deploy/windows/ (Windows / IIS)

Décompressez-le dans un répertoire de travail ; les commandes ci-dessous s’exécutent depuis celui-ci.

Étape 2 — Générer vos secrets

Keyright a besoin de trois secrets que vous créez et conservez. Générez-les maintenant :

openssl rand -hex 24                                                            # KEYRIGHT_ADMIN_TOKEN  (votre identifiant d'administration racine)
openssl rand -base64 32                                                         # KEYRIGHT_KEK          (chiffre les clés de signature au repos — 32 octets)
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform DER | base64 -w0   # KEYRIGHT_SIGNING_KEY  (facultatif ; signe les leases hors ligne)

(Sur macOS/BSD, base64 n’a pas d’option -w0 ; utilisez ... -outform DER | base64 | tr -d '\n'.)

Sauvegardez la KEK et la clé de signature séparément et de manière sécurisée. Elles sont à vous — nous ne les voyons jamais — et sans la KEK, les clés de signature chiffrées dans votre base de données ne peuvent pas être récupérées. La clé de signature est facultative (Keyright en génère une par tenant dans la base si vous l’omettez), mais si vous la définissez, sauvegardez-la aussi.

La signification complète de chaque variable se trouve dans Configuration.

Étape 3 — Préparer la 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 — il n’y a aucun fichier .sql et aucun SQL à exécuter à la main. Les migrations sont compilées dans l’image et appliquées automatiquement à chaque démarrage (db.Database.Migrate()).

Production — votre propre Postgres. Créez une base de données vide et un rôle de connexion, et faites de ce rôle le propriétaire de la base (la configuration correcte la plus simple — l’application doit pouvoir exécuter CREATE/ALTER/DROP pour appliquer les migrations) :

CREATE DATABASE keyright ENCODING 'UTF8' TEMPLATE template0;
CREATE ROLE keyright_app LOGIN PASSWORD 'a-strong-password';
ALTER DATABASE keyright OWNER TO keyright_app;

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 Flexible Server, Cloud SQL) n’autorisent pas CREATE DATABASE via SQL — créez la base vide + le rôle depuis leur console/CLI, puis accordez les droits comme ci-dessus. AWS RDS/Aurora, Cloud SQL, Azure, Neon, Supabase fonctionnent tous. Construisez ensuite votre chaîne de connexion (format Npgsql, TLS requis) :

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

Cette chaîne est votre KEYRIGHT_DB. Voir Configuration → Base de données pour les options TLS et les notes sur les fournisseurs managés.

Évaluation — sautez cette étape. Docker Compose et le chart Helm peuvent démarrer un postgres:16 pour vous, avec la base de données et le rôle pré-créés. Convient pour un premier essai et les petites installations à nœud unique ; passez à votre propre Postgres managé/HA pour la production.

Étape 4 — Déployer

Choisissez le mode qui correspond à votre environnement. Les trois produisent le même service en marche.

Étape 4A — Docker Compose (nœud unique)

Le moyen le plus rapide d’obtenir une instance en marche — Postgres + l’application sur un seul hôte :

cp deploy/.env.example deploy/.env        # puis renseignez les secrets de l'étape 2 (et KEYRIGHT_DB pour la production)
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d

Définissez votre licence dans deploy/.env sous KEYRIGHT_SELF_LICENSE (le JSON de la licence sur une seule ligne) ou montez un fichier et définissez KEYRIGHT_SELF_LICENSE_FILE (le kit contient un exemple de volumes: en commentaire). Épinglez une version avec KEYRIGHT_VERSION. En production, définissez un vrai KEYRIGHT_DB plutôt que le Postgres embarqué.

Étape 4B — Kubernetes (Helm)

Enregistrez votre licence dans license.json et passez-la avec --set-file — n’utilisez pas --set/--set-string pour la licence ni pour la chaîne de base de données : toutes deux contiennent des virgules/accolades que l’analyseur --set de Helm découpe, ce qui échoue avec key "…" has no value.

Production — votre propre Postgres externe (recommandé) :

helm upgrade --install keyright deploy/helm/keyright -n keyright --create-namespace \
  --set image.repository=ghcr.io/delta1-labs/keyright \
  --set-string secrets.adminToken="$KEYRIGHT_ADMIN_TOKEN" \
  --set-string secrets.kek="$KEYRIGHT_KEK" \
  --set-file  secrets.selfLicense=license.json \
  --set postgres.enabled=false \
  --set-string externalDatabase.connectionString="Host=db.example.com;Port=5432;Database=keyright;Username=keyright_app;Password=...;SSL Mode=Require;Trust Server Certificate=true" \
  --set replicaCount=2

Évaluation — Postgres embarqué dans le cluster (retirez les deux lignes de base de données ci-dessus et conservez la valeur par défaut) :

helm upgrade --install keyright deploy/helm/keyright -n keyright --create-namespace \
  --set image.repository=ghcr.io/delta1-labs/keyright \
  --set image.tag=2.2.2 \
  --set-string secrets.adminToken="$KEYRIGHT_ADMIN_TOKEN" \
  --set-string secrets.kek="$KEYRIGHT_KEK" \
  --set-file  secrets.selfLicense=license.json

Épinglez la version de l’image. Ajoutez --set image.tag=<version> (p. ex. --set image.tag=2.2.2) pour un déploiement reproductible. Non définie, elle prend par défaut l’appVersion du chart.

Limites de taux Docker Hub ? Le Postgres embarqué tire postgres:16 depuis Docker Hub, qui limite le débit des téléchargements anonymes. Si le pod postgres reste bloqué en ImagePullBackOff, pointez-le vers votre propre registre/miroir avec --set postgres.image=<registry>/postgres:16 (voir Configuration → Valeurs Kubernetes).

Attendez-vous à quelques redémarrages lors du premier démarrage avec le Postgres embarqué. Keyright exécute ses migrations au démarrage, et le Postgres embarqué met un moment à passer Ready — sur une installation d’évaluation toute neuve, le pod de l’application peut donc passer plusieurs fois en CrashLoopBackOff en attendant la base. C’est attendu, ce n’est pas une erreur ; cela se résorbe en une minute ou deux une fois Postgres Ready. Avec un Postgres externe, une boucle de crash persistante signifie en revanche que la base est réellement injoignable (voir Exploitation → Dépannage).

secrets.adminToken et secrets.kek sont obligatoires — le chart refuse de se rendre sans eux. Voir Configuration → Kubernetes pour l’ingress, les réplicas, les ressources, la marque blanche, le remplacement de l’image embarquée et l’accès au service via un port-forward.

Étape 4C — Windows / IIS

Pour les équipes qui n’exécuteront pas de conteneurs :

pwsh deploy/windows/build-win-bundle.ps1        # ajoutez -SelfContained si le serveur n'a pas .NET 8

Décompressez .artifacts/keyright-win/keyright-issuing-win-x64.zip dans le chemin physique d’un site IIS. Le web.config fourni câble l’ASP.NET Core Module (in-process). Définissez les valeurs KEYRIGHT_* comme variables d’environnement machine (de préférence) ou dans web.config, installez le .NET 8 Hosting Bundle, puis démarrez le site. Pointez KEYRIGHT_DB vers votre PostgreSQL.

Étape 5 — Vérifier

curl -fsS http://localhost:8080/health                                        # {"status":"ok","service":"keyright-issuing","version":"2.2.2"}
curl -H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" http://localhost:8080/admin/self-license

/health est la sonde de vivacité (liveness) ; /health/ready vérifie aussi la base de données. /admin/self-license indique votre édition, la phase (active / expiring / grace / gated), les jours restants et si le runtime est bloqué — s’il indique gated, votre licence ne s’est pas chargée (voir Licence).

Votre URL de base. Pour une exécution locale/d’évaluation, c’est http://localhost:<KEYRIGHT_PORT> (par défaut http://localhost:8080) ; en production, c’est l’hôte que sert votre répartiteur de charge (p. ex. https://licensing.acme.example). Chaque curl et chaque ServiceUrl de SDK à partir d’ici utilisent cette base.

Sur Kubernetes sans ingress, accédez au service via un port-forward. Le service se nomme <release>-keyright — pour la release keyright utilisée ci-dessus, c’est keyright-keyright :

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

Étape 6 — Se connecter au tableau de bord

Ouvrez <base>/dashboard. Sur une instance neuve, vous n’avez encore aucun utilisateur de tableau de bord — connectez-vous avec votre jeton admin : dépliez “Advanced: use an access token”, collez votre KEYRIGHT_ADMIN_TOKEN, puis View dashboard. (La connexion par e-mail/mot de passe nécessite un utilisateur provisionné via POST /admin/team/{id}/set-password ; le SSO est l’option Enterprise KEYRIGHT_SSO_*.) Le jeton admin est votre identifiant racine — traitez-le en conséquence.

C’est en marche — et ensuite

• Raccorder votre produit à votre instance — créez un produit, générez sa clé de signature, pointez le SDK de votre application vers votre URL de base et émettez votre première licence. C’est l’étape qui concrétise l’auto-hébergement.
• Licence et éditions — comment votre propre clé conditionne l’instance, l’essai et les renouvellements.
• Exploitation et dépannage — mise à l’échelle, sauvegardes, mises à niveau, isolé (air-gapped), et la solution à tout ce qui n’est pas passé au vert ci-dessus.

---

Bloqué sur une étape ? Contactez le service commercial/support — nous vous aiderons à démarrer.