Version 1.0.0-alpha.1dernière version
Chapitre 2.8
Installations sur machine unique
Installer Nexus sur un seul serveur Linux avec nexusctl, ou l'évaluer sur un ordinateur portable avec k3d, et accéder à la console en HTTPS afin que la connexion et les clés d'accès fonctionnent.
Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

Avant que la Harrow Port Authority n'installe Nexus sur son cluster de production, Tomás Reilly souhaitait réaliser deux installations plus modestes. La première était un projet pilote sur un serveur Linux de réserve dans le bâtiment des opérations, destiné aux douze personnes qui l'essaieraient en premier. La seconde tournait sur son propre ordinateur portable, afin qu'il puisse faire des tests et provoquer des pannes sans que personne ne s'en aperçoive. Ce chapitre couvre ces deux cas. Ils utilisent le même chart, les mêmes images et le même premier lancement qu'une installation Kubernetes complète ; ainsi, ce que vous apprenez sur une seule machine reste valable pour la suite.
L'approche sur serveur tient en une seule commande : nexusctl install --single-node construit un cluster k3s sur la machine, installe cert-manager, puis installe Nexus. L'approche sur ordinateur portable demande plus de manipulations. Vous construisez vous-même un cluster k3d, installez cert-manager et le chart avec Helm, puis effectuez une tâche supplémentaire qui piège presque tout le monde : vous placez la console derrière HTTPS sur votre propre machine, car une simple redirection de port (port-forward) ne permettra jamais à quiconque de se connecter.
Quelle taille doit avoir la machine
Avec les valeurs par défaut du chart, Nexus demande environ 2,05 cœurs de CPU (unité centrale de traitement) et 6,7 GiB de mémoire en réservations (requests), et ses volumes totalisent 142 GiB. Ce total comprend PostgreSQL (50), Valkey (5), Neo4j (20), Qdrant (10), le stockage d'objets (50), les deux stockages OpenBao (1 et 5) et le volume des reçus (1). Les demandes correspondent à ce que l'ordonnanceur réserve, et l'utilisation réelle est plus élevée une fois que les utilisateurs travaillent.
| Machine | CPU | Mémoire (RAM, mémoire vive) | Disque |
|---|---|---|---|
| Nœud unique recommandé | 8 vCPU | 32 GiB | 250 GB SSD (solid-state drive) |
| Minimum pour l'évaluation | 4 vCPU | 16 GiB | 200 GB |
Un ordinateur portable qui respecte le minimum requis pour l'évaluation fera tourner Nexus, mais c'est la limite de mémoire propre à Docker qui compte, et non celle de l'ordinateur. Allouez au moins 16 GiB à Docker avant de commencer.
Les deux approches nécessitent Kubernetes 1.33 ou une version ultérieure. L'approche à nœud unique apporte la sienne : k3s v1.33.6+k3s1, la distribution sur laquelle chaque version est testée.
Première partie : un serveur Linux avec nexusctl
Le serveur pilote de Tomás est une machine à 8 cœurs dotée de 32 GiB de mémoire et d'un SSD de 500 GB, exécutant une version actuelle de Linux sans rien d'autre installé. L'installation nécessite les privilèges root, car elle installe k3s en tant que service système.
Obtenir nexusctl et le vérifier
- Téléchargez
nexusctlpour votre architecture depuishttps://downloads.adverant.ai/nexus/1.0.0-alpha.1/, ainsi que la clé publique de la version. Enregistrez la clé sous le nomrelease.pub. Le chapitre 2.4, Obtenir et vérifier une version, explique comment contrôler l'empreinte de la clé par rapport à celle publiée par Adverant. - Vérifiez le binaire et la version à l'aide de la clé :
nexusctl version --json
nexusctl verifynexusctl verify vérifie le téléchargement à l'aide de la clé de version d'Adverant et refuse tout ce qu'il ne peut pas authentifier. En cas d'échec, arrêtez-vous et recommencez le téléchargement. Ne lancez jamais une installation à partir d'un fichier qui n'a pas pu être vérifié.
Créer la clé de dépositaire
Le magasin de clés de l'installation scelle ses clés de récupération à destination d'un ou plusieurs dépositaires (custodians). Un dépositaire est une personne qui détient un fichier d'identité age hors ligne, et le chart refuse de s'installer s'il n'y en a pas au moins un. Sur la machine du dépositaire :
age-keygen -o custodian.keyLe fichier commence par une ligne # public key: age1.... C'est cette partie publique qui doit être placée dans le fichier de valeurs. Le fichier d'identité lui-même ne quitte jamais la machine du dépositaire. Sur un Mac équipé d'une Secure Enclave, age-plugin-se keygen --access-control=any-biometry -o custodian.key crée une clé dont l'utilisation nécessite Touch ID, et sa partie publique commence par age1se1.
Rédiger le fichier de valeurs
# harrow-pilot-values.yaml (Helm values)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
enterprise:
enabled: false
tls:
mode: existing
existingSecret: harrow-public-tls
keys:
installationName: harrow-pilot
custody:
recipients:
- "<custodian-age-recipient>"<custodian-age-recipient> correspond à la ligne age1... issue de custodian.key. Ajoutez une entrée de liste par dépositaire.
keys.installationName est permanent. Le premier démarrage du magasin de clés génère l'identité de l'installation sous ce nom, et rien ne permet de la renommer par la suite. Il doit correspondre à ^[a-z][a-z0-9-]{0,62}$ : en minuscules, commençant par une lettre, 63 caractères au maximum. Ne copiez pas nexus-example ni le destinataire d'exemple provenant des fichiers d'exemple du chart. Le chart refuse les deux nommément, et la vérification préalable (preflight) signale ces mêmes codes en premier lieu.
Les trois hôtes constituent l'identité de l'installation. Chaque service refuse de démarrer sans eux, et chaque connexion, cookie et clé d'accès (passkey) est lié à hosts.console. Choisissez des noms que vous voudrez toujours utiliser dans cinq ans.
Faire pointer les trois noms vers le serveur
Les utilisateurs accèdent à la console, à l'API (interface de programmation d'application) et au service de connexion via le contrôleur Ingress intégré de k3s, Traefik, sur les ports 80 et 443 du serveur. Ajoutez trois enregistrements DNS (Domain Name System) pour console.harrow.example, api.harrow.example et auth.harrow.example, chacun pointant vers l'adresse du serveur. La vérification préalable contrôle chaque nom et vous indique lequel n'a pas d'enregistrement.
La politique réseau du chart n'autorise qu'un seul espace de noms (namespace) à joindre les trois services publics. Sa valeur par défaut, kube-system, correspond à l'endroit où k3s exécute Traefik ; par conséquent, sur un nœud unique, vous ne touchez pas à networkPolicy.ingressNamespace.
Exécuter la vérification préalable, puis installer
- Exécutez la vérification préalable avec l'option de nœud unique. Elle analyse la machine et votre fichier de valeurs sans rien modifier.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml- Lisez la ligne de résumé à la fin. Un avertissement ne bloque jamais l'installation, contrairement à un échec, et chaque ligne en échec comporte une indication
fix.
────────────────────────────────────────────────────────────
9 passed · 1 warning · 0 failed You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed
- Procédez à l'installation. L'option
--editiondoit concorder aveceditiondans le fichier de valeurs.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community- Observez le déroulement. Le programme exécute à nouveau la vérification préalable, installe k3s v1.33.6+k3s1, installe cert-manager v1.21.3, installe Nexus et attend que chaque service réponde à son contrôle d'état de santé. Sur le serveur de Tomás, cela a pris un peu moins de dix minutes.
done Preflight again 9 passed · 1 warning
done k3s v1.33.6+k3s1 node Ready
done cert-manager v1.21.3 ready
done Database and search ready
done Engines started
done Console https://console.harrow.example
Installed. Nobody can sign in yet.
Open https://console.harrow.example/claim
Code <code> works once, for 30 minutes
Fingerprint of this installation, to compare in the browser:
3F9A C21B 77E0 5D4C 9B12 A6F3 0E88 41D7
Gardez cette empreinte affichée à l'écran. Vous la comparerez dans le navigateur lorsque vous revendiquerez l'installation à l'aide du code. Si le code expire avant que vous ne l'utilisiez, nexusctl claim-code --administrator <email> en génère un nouveau. Le chapitre 2.12, Le premier lancement, prend le relais à partir de là.
Mettre le certificat en place
Avec tls.mode: existing, les trois routes Ingress servent le certificat contenu dans le Secret nommé par tls.existingSecret. Il doit couvrir les trois hôtes. La vérification préalable lit ce Secret lorsqu'il existe et émet un avertissement si le certificat expire dans moins de 30 jours. Lorsque le Secret n'est pas encore présent, la ligne vous invite à le créer, et il s'agit d'un avertissement et non d'un échec.
Sur un nœud unique, le cluster n'existe pas tant que l'installation ne l'a pas créé ; créez donc le Secret juste après l'installation. Extrayez d'abord le fichier kubeconfig du cluster (la dernière section de ce chapitre explique comment faire), puis utilisez-le pour créer le Secret :
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus create secret tls harrow-public-tls --cert=harrow-public.crt --key=harrow-public.keyharrow-public.crt contient le certificat suivi des éventuels certificats intermédiaires, et harrow-public.key contient sa clé privée. Si vos certificats proviennent d'une CA (autorité de certification) privée, nexusctl preflight et nexusctl install acceptent --ca-bundle <file> afin de pouvoir vérifier la chaîne. Les autres façons de gérer TLS (Transport Layer Security) sont décrites au chapitre 2.11, Variantes : stockages externes, TLS et Ingress.
En cas d'échec
| Ce que vous voyez | Ce que cela signifie | Que faire |
|---|---|---|
PREFLIGHT_FAILED (409) |
La vérification préalable a détecté un échec, l'installation n'a donc pas démarré. Rien n'a été installé. | Corrigez chaque ligne en échec à l'aide de son indication fix, puis relancez l'installation. |
INSTALLATION_NAME_MISSING |
keys.installationName est vide. |
Définissez le nom permanent propre à l'installation. |
INSTALLATION_NAME_EXAMPLE |
Le nom correspond à celui des valeurs d'exemple du chart. | Choisissez votre propre nom. |
KEYS_CUSTODIAN_MISSING |
keys.custody.recipients est vide. |
Ajoutez le destinataire age1... public de chaque dépositaire. |
KEYS_CUSTODIAN_EXAMPLE |
L'un des destinataires est le dépositaire d'exemple du chart, dont personne ne détient l'identité. | Remplacez-le par les destinataires de vos dépositaires. |
nexusctl renvoie le code de sortie 0 lorsqu'il peut poursuivre, 1 lorsqu'une vérification l'a bloqué, et 2 lorsqu'il n'a pas pu s'exécuter du tout (fichier de valeurs illisible, option erronée). Un script peut s'appuyer sur ces trois valeurs pour créer des embranchements.
Deuxième partie : une évaluation sur un ordinateur portable avec k3d
k3d exécute k3s à l'intérieur de conteneurs Docker, de sorte qu'un cluster entier réside sur un ordinateur portable et disparaît en une seule commande. Les outils de publication qui testent chaque version de Nexus construisent leurs clusters exactement de cette manière, et copier leurs paramètres vous évite de redécouvrir les problèmes qu'ils ont déjà rencontrés.
Vous avez besoin de Docker, k3d 5.8.3, kubectl, Helm v4 et Chrome. Tomás a utilisé son Mac.
Créer le cluster
k3d cluster create harrow-eval --agents 0 --wait --timeout 300s \
--image rancher/k3s:v1.33.6-k3s1 \
--k3s-arg "--disable=traefik@server:0"
k3d kubeconfig get harrow-eval > harrow-eval.kubeconfig
chmod 600 harrow-eval.kubeconfig
export KUBECONFIG=$PWD/harrow-eval.kubeconfigChaque option a sa raison d'être.
--agents 0fournit un nœud serveur et aucun nœud de travail (worker). Nexus fonctionne parfaitement sur un seul nœud, et un second ne ferait que consommer de la mémoire.--image rancher/k3s:v1.33.6-k3s1fige la version de k3s sur laquelle chaque version est testée. Sans cela, vous obtenez la version par défaut de k3d.--disable=traefik@server:0exclut Traefik. Un ordinateur portable n'a pas d'adresse publique à servir, et vous accédez plutôt à la console via votre propre frontal HTTPS (voir ci-dessous).--wait --timeout 300sne rend la main que lorsque le cluster répond, ou échoue au bout de cinq minutes.
Si vous hébergez un miroir du registre de versions sur votre ordinateur portable, ajoutez --registry-config <registries.yaml> pour diriger les téléchargements d'images vers le miroir, et --k3s-arg "--disable-default-registry-endpoint@server:0" pour éviter tout repli vers un registre en amont. Les outils de publication fonctionnent ainsi, chaque image provenant exclusivement du miroir.
Installer cert-manager
Le chart crée sa propre CA locale, nexus-local-ca, en tant qu'émetteur cert-manager, et chaque service obtient son certificat auprès d'elle. Sans les ressources de cert-manager dans le cluster, helm install refuse le chart en quelques secondes. Installez d'abord cert-manager v1.21.3 à partir du chart publié par le projet cert-manager :
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10mNexus n'a besoin de rien d'autre de la part de cert-manager, et en particulier d'aucun trust-manager.
Installer Nexus
- Rédigez un fichier de valeurs pour l'ordinateur portable. Le protocole TLS se termine au niveau de votre propre frontal, donc
tls.modea pour valeurnone.
# harrow-eval-values.yaml (Helm values)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
tls:
mode: none
keys:
installationName: harrow-eval
custody:
recipients:
- "<custodian-age-recipient>"- Installez le chart depuis le registre et omettez
--wait(l'avertissement ci-dessous explique pourquoi).
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
-n nexus --create-namespace -f harrow-eval-values.yaml --timeout 45m- Attendez ensuite vous-même que les charges de travail soient prêtes :
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
for s in $(kubectl -n nexus get sts -o name); do
want=$(kubectl -n nexus get "$s" -o jsonpath='{.spec.replicas}')
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'="$want" --timeout=900s
doneLa boucle sur les StatefulSets est présente car certains d'entre eux mettent à jour un pod à la fois sur demande, et kubectl rollout status les refuse. Attendre sur readyReplicas fonctionne pour toutes les stratégies de mise à jour.
Lorsque les deux commandes rendent la main, chaque Deployment est à l'état Available et tous les pods de chaque StatefulSet sont prêts. Personne ne peut encore se connecter. C'est normal : l'installation n'a pas encore été revendiquée.
Pourquoi une redirection de port ne permet jamais de se connecter
L'étape suivante qui semble évidente consiste à lancer kubectl port-forward svc/nexus-alpha 3000:3000 et à ouvrir un navigateur sur http://127.0.0.1:3000. Les pages de la console se chargent, ce qui donne l'impression que cela fonctionne. Ce n'est pas le cas, et aucun réglage ne permettra de le faire fonctionner. Trois éléments s'y opposent, chacun délibérément.
| Ce qui bloque | Pourquoi |
|---|---|
| L'origine | Le système de connexion de la console refuse toute requête dont l'origine n'est pas https://<hosts.console>, ici https://console.harrow.example. Une page servie depuis http://127.0.0.1:3000 n'a pas la bonne origine, si bien que la connexion ne démarre jamais. |
| Le cookie | La session repose sur un cookie __Host- marqué Secure. Les navigateurs ne stockent un tel cookie que via HTTPS, sans attribut de domaine, et uniquement pour l'hôte exact qui l'a défini. En HTTP simple, le navigateur le rejette. |
| La clé d'accès (passkey) | Le premier administrateur se connecte avec une clé d'accès, et une clé d'accès nécessite un contexte sécurisé doté d'un certificat valide. Chrome refuse de créer une clé d'accès derrière un avertissement de certificat, même si vous avez cliqué pour passer outre. |
Le navigateur doit donc communiquer avec https://console.harrow.example, à l'aide d'un certificat auquel il fait confiance, et ce nom doit mener à votre ordinateur portable.
Accéder à la console en HTTPS sur votre ordinateur portable
La méthode ci-dessous utilise la propre CA du chart pour émettre le certificat, une redirection de port pour joindre la console, et un profil Chrome distinct qui fait confiance à cette seule CA et associe le nom de la console à votre ordinateur portable. Le magasin de certificats de confiance de votre système et /etc/hosts restent intacts.
Émettre un certificat pour le nom de la console
- Demandez à cert-manager un certificat pour l'hôte de la console, signé par l'émetteur du chart :
# console-front-certificate.yaml (a cert-manager Certificate)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: nexus-console-front
namespace: nexus
spec:
secretName: nexus-console-front-tls
dnsNames: [console.harrow.example]
duration: 24h
usages: [server auth, digital signature, key encipherment]
privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
issuerRef: { name: nexus-local-ca, kind: Issuer, group: cert-manager.io }kubectl apply -f console-front-certificate.yaml
kubectl -n nexus wait --for=condition=Ready certificate/nexus-console-front --timeout=120scert-manager le signe à l'intérieur du cluster. Vous ne lisez jamais la clé privée de la CA.
- Copiez le certificat, sa clé et le certificat de la CA hors du Secret :
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
chmod 600 tls.key- Calculez l'empreinte d'épinglage (pin) de la CA. Chrome identifie une clé de confiance par le hachage SHA-256 en base64 de sa clé publique :
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64Épinglez la clé de la CA, et non celle du certificat. Le certificat a une durée de vie d'un jour et reçoit une nouvelle clé chaque fois que cert-manager le renouvelle, tandis que la CA reste la même.
Placer un frontal HTTPS devant une redirection de port
- Redirigez le Service de la console. Son port est celui nommé
http, qui correspond à 3000 dans cette version :
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000- Exécutez un écouteur HTTPS sur
127.0.0.1:28443qui redirige vers127.0.0.1:3000. N'importe quel proxy inverse auquel vous faites déjà confiance conviendra, tant qu'il accomplit quatre choses :- sert
tls.crtsuivi deca.crten tant que chaîne, avectls.key; - conserve l'en-tête
Hostavec la valeurconsole.harrow.example; - définit
X-Forwarded-Proto: https; - laisse passer les mises à niveau (upgrades) WebSocket, car la console les utilise.
- sert
Une redirection de port vers un Service se lie à l'unique pod qu'elle a sélectionné au démarrage. Après qu'une mise à niveau ou un redémarrage a remplacé le pod de la console, la redirection reste active mais ne pointe plus vers rien, et le navigateur affiche une erreur de passerelle incorrecte (bad gateway). Redémarrez la redirection de port chaque fois que le pod de la console change.
Ouvrir Chrome avec l'épinglage et la correspondance de nom
Sur un Mac :
open -na "Google Chrome" --args --user-data-dir="$HOME/.nexus-eval-chrome" \
"--host-resolver-rules=MAP console.harrow.example:443 127.0.0.1:28443" \
"--ignore-certificate-errors-spki-list=<ca-pin>" \
https://console.harrow.example/install<ca-pin> correspond à la sortie de la ligne openssl. Sous Linux, lancez Chrome avec les trois mêmes options.
Les trois options fonctionnent de concert. --host-resolver-rules envoie console.harrow.example sur le port 443 vers votre frontal, uniquement au sein de ce profil. --ignore-certificate-errors-spki-list fait confiance aux certificats émis par cette seule clé de CA, et Chrome ne l'applique qu'en présence de --user-data-dir. Le profil séparé maintient cette exception à l'écart de votre navigation quotidienne. Il ne s'agit pas d'un interrupteur global permettant d'« ignorer les erreurs de certificat » : tout ce qui n'est pas signé par la CA du cluster continue d'échouer.
Avec ce profil ouvert, https://console.harrow.example/install mène à la page de revendication et une clé d'accès peut être créée. Le chapitre 2.12, Le premier lancement, reprend à partir de là.
Lorsque l'ordinateur portable redémarre
Le magasin de clés comporte deux parties : le magasin de clés lui-même et un petit service de descellement (unsealer) qui détient sa clé de déverrouillage. Après tout redémarrage du nœud (un redémarrage de Docker, un redémarrage de l'ordinateur portable, k3d cluster stop et start), le service de descellement démarre à l'état scellé. Le magasin de clés se descelle par son intermédiaire ; par conséquent, tant qu'un dépositaire n'a pas descellé ce service à l'aide de sa propre identité age, rien de ce qui nécessite une clé ne fonctionne. C'est une propriété inhérente à la conception du système, et il en va de même sur un cluster de production. Le chapitre 2.15, Jour 2 : exploiter Nexus, présente la procédure de descellement.
Lorsque vous avez terminé l'évaluation :
k3d cluster delete harrow-evalLa suppression du cluster supprime l'installation ainsi que tout ce qu'elle contient.
nexusctl kubeconfig
Un cluster construit par nexusctl install --single-node appartient à nexusctl. Pour y accéder avec kubectl, helm ou tout autre outil, demandez son fichier kubeconfig :
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulsetCe fichier accorde un accès administratif complet au cluster. Conservez-le avec les permissions 600, sur les machines des personnes qui gèrent l'installation, et nulle part ailleurs. Toutes les commandes ultérieures de la Partie 2 qui acceptent --context ou lisent KUBECONFIG fonctionnent sur un nœud unique par le biais de ce fichier. Il en va de même pour une mise à niveau : nexusctl upgrade plan --bundle <file> et nexusctl upgrade apply --bundle <file> sur un nœud unique mettent également à niveau le cluster k3s détenu par nexusctl.
nexusctl install --single-node installe sur un serveur Linux unique.Ce qui est conservé lors du passage à un cluster
Tout ce que vous avez fait sur une seule machine a son équivalent sur un cluster. Le fichier de valeurs reste le même, à l'exception d'un registre, d'un mode TLS ou d'une classe de stockage différents, comme le montre le chapitre 2.11, Variantes : stockages externes, TLS et Ingress. Le premier lancement est identique. Ce qui n'est pas transférable, c'est l'installation elle-même : le nom de l'installation est fixé définitivement, et une installation ne peut pas être déplacée d'un ordinateur portable vers un serveur. Lorsque Tomás est passé de son ordinateur portable au serveur pilote, il est reparti de zéro avec un nouveau nom, harrow-pilot, et a conservé harrow-eval pour ses expérimentations.
