Versie 1.0.0-alpha.1nieuwste
Hoofdstuk 2.8
Installaties op één machine
Installeer Nexus op één Linux-server met nexusctl, of evalueer het op een laptop met k3d, en bereik de console via HTTPS zodat aanmelden en passkeys werken.
Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

Voordat Harrow Port Authority Nexus op haar productiecluster plaatste, wilde Tomás Reilly twee kleinere installaties. De ene was een pilot op een niet-gebruikte Linux-server in het operationele gebouw, voor de twaalf mensen die het als eersten zouden uitproberen. De andere draaide op zijn eigen laptop, zodat hij dingen kapot kon maken zonder dat iemand het merkte. Dit hoofdstuk behandelt beide. Ze gebruiken dezelfde chart, dezelfde images en dezelfde eerste uitvoering als een volledige Kubernetes-installatie, dus wat u op één machine leert, neemt u mee.
Het servertraject bestaat uit één opdracht: nexusctl install --single-node bouwt een k3s-cluster op de machine, installeert cert-manager en installeert vervolgens Nexus. Het laptoptraject vraagt meer handwerk. U bouwt zelf een k3d-cluster, installeert cert-manager en de chart met Helm en voert daarna één extra taak uit waar bijna iedereen tegenaan loopt: u zet de console op uw eigen machine achter HTTPS, omdat een gewone port-forward nooit iemand kan aanmelden.
Hoe groot de machine moet zijn
Nexus vraagt met de standaardwaarden van de chart om ongeveer 2.05 CPU-cores (central processing unit) en 6.7 GiB geheugen aan requests, en de volumes tellen op tot 142 GiB. Dat totaal bestaat uit PostgreSQL 50, Valkey 5, Neo4j 20, Qdrant 10, de objectopslag 50, de twee OpenBao-opslagplaatsen 1 en 5, en het ontvangstbewijzenvolume 1. Requests zijn wat de scheduler reserveert; het werkelijke gebruik ligt hoger zodra mensen aan het werk zijn.
| Machine | CPU | Geheugen (RAM, random-access memory) | Schijf |
|---|---|---|---|
| Aanbevolen voor enkele node | 8 vCPU | 32 GiB | 250 GB SSD (solid-state drive) |
| Minimum voor evaluatie | 4 vCPU | 16 GiB | 200 GB |
Een laptop die aan het evaluatieminimum voldoet kan Nexus draaien, maar de geheugenlimiet van Docker zelf telt, niet die van de laptop. Geef Docker ten minste 16 GiB voordat u begint.
Beide trajecten vereisen Kubernetes 1.33 of hoger. Het traject voor een enkele node neemt zijn eigen distributie mee: k3s v1.33.6+k3s1, de distributie waarop elke release wordt getest.
Deel één: één Linux-server met nexusctl
De pilotserver van Tomás is een machine met 8 cores, 32 GiB geheugen en een SSD van 500 GB, waarop een courante Linux-versie draait en verder niets. De installatie vereist root, omdat k3s als systeemservice wordt geïnstalleerd.
nexusctl ophalen en controleren
- Download
nexusctlvoor uw architectuur vanafhttps://downloads.adverant.ai/nexus/1.0.0-alpha.1/, samen met de publieke sleutel van de release. Sla de sleutel op alsrelease.pub. Hoofdstuk 2.4, Een release ophalen en verifiëren, legt uit hoe u de vingerafdruk van de sleutel controleert aan de hand van de vingerafdruk die Adverant publiceert. - Controleer het binaire bestand en de release met de sleutel:
nexusctl version --json
nexusctl verifynexusctl verify controleert de download aan de hand van de Adverant-releasesleutel en weigert alles wat niet kan worden geverifieerd. Als dit mislukt, stopt u en downloadt u opnieuw. Voer nooit een installatie uit vanaf een bestand dat niet is geverifieerd.
De bewaarderssleutel aanmaken
De sleutelopslag van de installatie verzegelt de herstelsleutels voor een of meer bewaarders (custodians). Een bewaarder is een persoon die offline een age-identiteitsbestand bewaart, en de chart weigert te installeren zonder ten minste één bewaarder. Op de eigen machine van de bewaarder:
age-keygen -o custodian.keyHet bestand begint met een regel # public key: age1.... Die publieke helft gaat in het values-bestand. Het identiteitsbestand zelf verlaat nooit de machine van de bewaarder. Op een Mac met een Secure Enclave maakt age-plugin-se keygen --access-control=any-biometry -o custodian.key een sleutel aan waarvoor Touch ID nodig is om deze te gebruiken, en de publieke helft daarvan begint met age1se1.
Het values-bestand schrijven
# 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> is de regel age1... uit custodian.key. Voeg één lijstitem per bewaarder toe.
keys.installationName is permanent. Bij de eerste start van de sleutelopslag wordt de identiteit van de installatie onder die naam vastgelegd, en niets kan die naam daarna nog wijzigen. De naam moet voldoen aan ^[a-z][a-z0-9-]{0,62}$: kleine letters, beginnend met een letter, maximaal 63 tekens. Kopieer niet nexus-example of de voorbeeldontvanger uit de voorbeeldbestanden van de chart zelf. De chart weigert beide op naam, en preflight meldt eerst dezelfde codes.
De drie hosts vormen de identiteit van de installatie. Elke service weigert te starten zonder deze hosts, en elke aanmelding, cookie en passkey is gekoppeld aan hosts.console. Kies namen die u over vijf jaar nog steeds wilt gebruiken.
De drie namen naar de server laten verwijzen
Gebruikers bereiken de console, de API (application programming interface) en de aanmeldservice via de ingebouwde ingress-controller van k3s, Traefik, op poort 80 en 443 van de server. Voeg drie DNS-records (Domain Name System) toe voor console.harrow.example, api.harrow.example en auth.harrow.example, die elk naar het adres van de server verwijzen. Preflight controleert elke naam en vertelt u voor welke naam er geen record is.
Het netwerkbeleid van de chart staat slechts één namespace toe om de drie publieke services te bereiken. De standaardwaarde, kube-system, is waar k3s Traefik uitvoert, dus op een enkele node laat u networkPolicy.ingressNamespace ongewijzigd.
Preflight uitvoeren en vervolgens installeren
- Voer preflight uit met de vlag voor een enkele node. Dit leest de machine en uw values-bestand uit en wijzigt niets.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml- Lees de samenvattingsregel aan het einde. Een waarschuwing blokkeert de installatie nooit, maar een fout wel, en elke falende rij bevat een
fix-regel.
────────────────────────────────────────────────────────────
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
- Installeer. De vlag
--editionmoet overeenkomen meteditionin het values-bestand.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community- Kijk hoe het proces verloopt. Het voert preflight opnieuw uit, installeert k3s v1.33.6+k3s1, installeert cert-manager v1.21.3, installeert Nexus en wacht tot elke service op zijn healthcheck antwoordt. Op de server van Tomás duurde dit iets minder dan tien minuten.
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
Houd die vingerafdruk op het scherm. U vergelijkt deze in de browser wanneer u de installatie met de code claimt. Als de code verloopt voordat u deze gebruikt, maakt nexusctl claim-code --administrator <email> een nieuwe aan. Hoofdstuk 2.12, De eerste uitvoering, gaat vanaf daar verder.
Het certificaat plaatsen
Met tls.mode: existing serveren de drie ingress-routes het certificaat in het Secret dat wordt genoemd door tls.existingSecret. Dit moet alle drie de hosts dekken. Preflight leest dat Secret wanneer het bestaat en waarschuwt wanneer het certificaat binnen 30 dagen verloopt. Wanneer het Secret er nog niet is, vertelt de rij u dat u het moet aanmaken; dat is een waarschuwing, geen fout.
Op een enkele node bestaat het cluster pas nadat de installatie het heeft aangemaakt, dus maakt u het Secret direct na de installatie aan. Schrijf eerst de kubeconfig van het cluster weg (de laatste paragraaf van dit hoofdstuk legt dit uit) en maak vervolgens het Secret daarmee aan:
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 bevat het certificaat gevolgd door eventuele tussencertificaten, en harrow-public.key de bijbehorende privésleutel. Als uw certificaten afkomstig zijn van een particuliere CA (certificate authority), accepteren nexusctl preflight en nexusctl install --ca-bundle <file> zodat ze de keten kunnen controleren. De andere manieren om met TLS (Transport Layer Security) om te gaan staan in hoofdstuk 2.11, Variaties: externe opslag, TLS en ingress.
Als dit mislukt
| Wat u ziet | Wat het betekent | Wat te doen |
|---|---|---|
PREFLIGHT_FAILED (409) |
Preflight heeft een fout gevonden, waardoor de installatie niet is gestart. Er is niets geïnstalleerd. | Los elke falende rij op aan de hand van de bijbehorende fix-regel en voer de installatie opnieuw uit. |
INSTALLATION_NAME_MISSING |
keys.installationName is leeg. |
Stel de eigen permanente naam van de installatie in. |
INSTALLATION_NAME_EXAMPLE |
De naam is die uit de voorbeeldwaarden van de chart. | Kies uw eigen naam. |
KEYS_CUSTODIAN_MISSING |
keys.custody.recipients is leeg. |
Voeg van elke bewaarder de publieke age1...-ontvanger toe. |
KEYS_CUSTODIAN_EXAMPLE |
Een ontvanger is de voorbeeldbewaarder van de chart, van wie niemand de identiteit bezit. | Vervang deze door de ontvangers van uw bewaarders. |
nexusctl sluit af met 0 wanneer het door kan gaan, 1 wanneer een controle het heeft geblokkeerd en 2 wanneer het helemaal niet kon worden uitgevoerd (een onleesbaar values-bestand, een verkeerde vlag). Een script kan op die drie waarden vertakken.
Deel twee: een evaluatie op een laptop met k3d
k3d voert k3s uit binnen Docker-containers, zodat een heel cluster op een laptop staat en met één opdracht weer verdwijnt. De releasetools die elke Nexus-release testen, bouwen hun clusters precies op deze manier, en door hun instellingen over te nemen voorkomt u dat u de problemen die zij al zijn tegengekomen opnieuw moet ontdekken.
U hebt Docker, k3d 5.8.3, kubectl, Helm v4 en Chrome nodig. Tomás gebruikte zijn Mac.
Het cluster aanmaken
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.kubeconfigElke vlag heeft een reden.
--agents 0geeft één servernode en geen workers. Nexus draait probleemloos op één node, en een tweede kost alleen maar geheugen.--image rancher/k3s:v1.33.6-k3s1zet de k3s-versie vast waarop elke release wordt getest. Zonder deze vlag krijgt u wat k3d standaard gebruikt.--disable=traefik@server:0laat Traefik weg. Een laptop heeft geen publiek adres om te bedienen, en u bereikt de console in plaats daarvan via uw eigen HTTPS-voorzijde (hieronder).--wait --timeout 300skeert pas terug wanneer het cluster antwoordt, of mislukt na vijf minuten.
Als u de releaseregistry op uw laptop spiegelt, voegt u --registry-config <registries.yaml> toe om het ophalen van images naar de mirror te sturen, en --k3s-arg "--disable-default-registry-endpoint@server:0" zodat niets terugvalt op een upstream-registry. De releasetools draaien op deze manier, waarbij elke image uitsluitend via de mirror binnenkomt.
cert-manager installeren
De chart maakt zijn eigen lokale CA, nexus-local-ca, aan als een cert-manager-issuer, en elke service krijgt zijn certificaat daarvan. Zonder de resources van cert-manager in het cluster weigert helm install de chart binnen enkele seconden. Installeer eerst cert-manager v1.21.3, vanaf de chart die het cert-manager-project publiceert:
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10mNexus heeft verder niets nodig van cert-manager, en in het bijzonder geen trust-manager.
Nexus installeren
- Schrijf een values-bestand voor de laptop. TLS eindigt bij uw eigen voorzijde, dus
tls.modeisnone.
# 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>"- Installeer de chart vanuit de registry en laat
--waitweg (de waarschuwing hieronder legt uit waarom).
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- Wacht vervolgens zelf op de workloads:
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
doneDe StatefulSet-lus staat er omdat sommige daarvan op verzoek één pod tegelijk bijwerken, en kubectl rollout status weigert die. Wachten op readyReplicas werkt voor elke updatestrategie.
Wanneer beide opdrachten terugkeren, is elke Deployment Available en heeft elke StatefulSet zijn pods gereed. Niemand kan zich nog aanmelden. Dat klopt: de installatie is nog niet geclaimd.
Waarom u zich met een port-forward nooit kunt aanmelden
De voor de hand liggende volgende stap is kubectl port-forward svc/nexus-alpha 3000:3000 en een browser op http://127.0.0.1:3000. De pagina's van de console worden geladen, dus het lijkt alsof het werkt. Dat is niet zo, en geen enkele instelling zal het laten werken. Drie dingen staan in de weg, elk met opzet.
| Wat het tegenhoudt | Waarom |
|---|---|
| De origin | De aanmelding van de console weigert een verzoek waarvan de origin niet https://<hosts.console> is, hier https://console.harrow.example. Een pagina die wordt geserveerd vanaf http://127.0.0.1:3000 heeft de verkeerde origin, waardoor het aanmelden nooit start. |
| De cookie | De sessie is een __Host--cookie gemarkeerd als Secure. Browsers slaan zo'n cookie alleen op via HTTPS, zonder domeinattribuut, voor precies de host die deze heeft ingesteld. Via gewoon HTTP gooit de browser de cookie weg. |
| De passkey | De eerste beheerder meldt zich aan met een passkey, en een passkey vereist een beveiligde context met een geldig certificaat. Chrome weigert een passkey aan te maken achter een certificaatwaarschuwing, zelfs als u daar doorheen hebt geklikt. |
De browser moet dus praten met https://console.harrow.example, met een certificaat dat hij vertrouwt, en die naam moet naar uw laptop leiden.
De console via HTTPS bereiken op uw laptop
De onderstaande methode gebruikt de eigen CA van de chart om het certificaat uit te geven, een port-forward om de console te bereiken, en een apart Chrome-profiel dat die ene CA vertrouwt en de naam van de console aan uw laptop koppelt. Uw systeem-truststore en /etc/hosts blijven zoals ze zijn.
Een certificaat uitgeven voor de naam van de console
- Vraag cert-manager om een certificaat voor de consolehost, ondertekend door de issuer van de 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 ondertekent het binnen het cluster. U leest nooit de privésleutel van de CA.
- Kopieer het certificaat, de bijbehorende sleutel en het CA-certificaat uit het 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- Bepaal de pin van de CA. Chrome identificeert een vertrouwde sleutel aan de hand van de base64 SHA-256 van de publieke sleutel:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64Pin de sleutel van de CA, niet die van het certificaat. Het certificaat is een dag geldig en krijgt telkens een nieuwe sleutel wanneer cert-manager het vernieuwt, terwijl de CA hetzelfde blijft.
Een HTTPS-voorzijde voor een port-forward plaatsen
- Stuur de Service van de console door. De poort is degene met de naam
http, wat in deze release 3000 is:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000- Voer een HTTPS-listener uit op
127.0.0.1:28443die doorstuurt naar127.0.0.1:3000. Elke reverse proxy die u al vertrouwt volstaat, zolang deze vier dingen doet:- serveert
tls.crtgevolgd doorca.crtals de keten, mettls.key; - behoudt de
Host-header alsconsole.harrow.example; - stelt
X-Forwarded-Proto: httpsin; - laat WebSocket-upgrades door, omdat de console deze gebruikt.
- serveert
Een port-forward naar een Service bindt de ene pod die hij koos toen hij startte. Nadat een upgrade of een herstart de console-pod vervangt, blijft de forward actief en stuurt hij door naar niets, waardoor de browser een bad gateway toont. Herstart de port-forward telkens wanneer de console-pod verandert.
Chrome openen met de pin en de naamkoppeling
Op een 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> is de uitvoer van de openssl-regel. Start op Linux Chrome met dezelfde drie vlaggen.
De drie vlaggen werken samen. --host-resolver-rules stuurt console.harrow.example op poort 443 naar uw voorzijde, alleen binnen dit profiel. --ignore-certificate-errors-spki-list vertrouwt certificaten die zijn uitgegeven door die ene CA-sleutel, en Chrome honoreert dit alleen met --user-data-dir. Het aparte profiel houdt de uitzondering weg van uw dagelijkse browsegedrag. Het is geen algemene schakelaar om "certificaatfouten te negeren": alles wat niet is ondertekend door de CA van het cluster mislukt nog steeds.
Met dat profiel geopend leidt https://console.harrow.example/install naar de claimpagina en kan er een passkey worden aangemaakt. Hoofdstuk 2.12, De eerste uitvoering, gaat vanaf hier verder.
Wanneer de laptop herstart
De sleutelopslag bestaat uit twee delen: de sleutelopslag zelf en een kleine unsealer die de ontgrendelingssleutel bewaart. Na elke herstart van de node (een herstart van Docker, een herstart van de laptop, k3d cluster stop en start) start de unsealer verzegeld. De sleutelopslag ontzegelt zichzelf via de unsealer, dus totdat een bewaarder de unsealer ontzegelt met zijn eigen age-identiteit, werkt niets dat een sleutel nodig heeft. Dat is een eigenschap van het ontwerp, en het werkt net zo op een productiecluster. Hoofdstuk 2.15, Dag twee: werken met Nexus, laat het ontzegelen zien.
Wanneer u klaar bent met de evaluatie:
k3d cluster delete harrow-evalDoor het cluster te verwijderen, verwijdert u de installatie en alles wat erin zit.
nexusctl kubeconfig
Een cluster dat door nexusctl install --single-node is gebouwd, is eigendom van nexusctl. Om het te bereiken met kubectl, helm of een andere tool, vraagt u om de bijbehorende kubeconfig:
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulsetHet bestand verleent volledige beheerderstoegang tot het cluster. Bewaar het met modus 600 op de machines van de mensen die de installatie beheren, en nergens anders. Elke latere opdracht in Deel 2 die --context accepteert of KUBECONFIG leest, werkt via dit bestand tegen een enkele node. Hetzelfde geldt voor een upgrade: nexusctl upgrade plan --bundle <file> en nexusctl upgrade apply --bundle <file> op een enkele node upgraden ook het k3s-cluster dat eigendom is van nexusctl.
nexusctl install --single-node op één Linux-server plaatst.Wat meegaat naar een cluster
Alles wat u op één machine hebt gedaan, heeft een equivalent op een cluster. Het values-bestand is hetzelfde bestand met een andere registry, TLS-modus of opslagklasse, zoals hoofdstuk 2.11, Variaties: externe opslag, TLS en ingress, laat zien. De eerste uitvoering is identiek. Wat niet kan worden meegenomen, is de installatie zelf: de installatienaam ligt voorgoed vast en een installatie kan niet van een laptop naar een server worden verplaatst. Toen Tomás van zijn laptop naar de pilotserver overstapte, begon hij opnieuw met een nieuwe naam, harrow-pilot, en hield hij harrow-eval aan voor experimenten.
