Version 1.0.0-alpha.1senaste
Kapitel 2.8
Installationer på en enskild maskin
Installera Nexus på en Linux-server med nexusctl, eller utvärdera det på en bärbar dator med k3d, och nå konsolen via HTTPS så att inloggning och nycklar (passkeys) fungerar.
Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

Innan Harrow Port Authority lade Nexus på sitt produktionskluster ville Tomás Reilly ha två mindre installationer. Den ena var en pilot på en ledig Linux-server i driftbyggnaden, för de tolv personer som skulle prova det först. Den andra kördes på hans egen bärbara dator, så att han kunde ta sönder saker utan att någon märkte det. Det här kapitlet behandlar båda. De använder samma chart, samma avbildningar och samma första körning som en fullständig Kubernetes-installation, så det ni lär er på en maskin kan ni ta med er vidare.
Servervägen är ett enda kommando: nexusctl install --single-node bygger ett k3s-kluster på maskinen, installerar cert-manager och installerar sedan Nexus. Vägen för bärbar dator kräver mer handpåläggning. Ni bygger ett k3d-kluster själva, installerar cert-manager och charten med Helm, och utför sedan ett extra moment som nästan alla fastnar på: ni sätter konsolen bakom HTTPS på er egen maskin, eftersom en enkel portvidarebefordran aldrig kan logga in någon.
Hur stor maskinen måste vara
Nexus begär omkring 2.05 CPU-kärnor (central processing unit) och 6.7 GiB minne med chartens standardvärden, och dess volymer uppgår till totalt 142 GiB. Den summan består av PostgreSQL 50, Valkey 5, Neo4j 20, Qdrant 10, objektlagringen 50, de två OpenBao-lagren 1 och 5 samt kvittovolymen 1. Begärda resurser (requests) är vad schemaläggaren reserverar, och den faktiska förbrukningen blir högre när användarna väl börjar arbeta.
| Maskin | CPU | Minne (RAM, random-access memory) | Disk |
|---|---|---|---|
| Rekommenderad enskild nod | 8 vCPU | 32 GiB | 250 GB SSD (solid-state drive) |
| Minimum för utvärdering | 4 vCPU | 16 GiB | 200 GB |
En bärbar dator som uppfyller minimikraven för utvärdering kan köra Nexus, men det är Dockers egen minnesgräns som räknas, inte datorns. Ge Docker minst 16 GiB innan ni börjar.
Båda vägarna kräver Kubernetes 1.33 eller senare. Vägen för en enskild nod har med sig sin egen: k3s v1.33.6+k3s1, den distribution som varje utgåva testas på.
Del ett: en Linux-server med nexusctl
Tomás pilotserver är en maskin med 8 kärnor, 32 GiB minne och en 500 GB SSD, som kör en aktuell Linux-version utan något annat installerat. Installationen kräver root-behörighet, eftersom den installerar k3s som en systemtjänst.
Hämta nexusctl och kontrollera den
- Ladda ner
nexusctlför er arkitektur frånhttps://downloads.adverant.ai/nexus/1.0.0-alpha.1/, tillsammans med utgåvans publika nyckel. Spara nyckeln somrelease.pub. Kapitel 2.4, Hämta och verifiera en utgåva, förklarar hur ni kontrollerar nyckelns fingeravtryck mot det som Adverant publicerar. - Kontrollera binärfilen och utgåvan med nyckeln:
nexusctl version --json
nexusctl verifynexusctl verify kontrollerar nedladdningen mot Adverants utgivningsnyckel och avvisar allt som inte kan verifieras. Om det misslyckas, avbryt och ladda ner på nytt. Kör aldrig en installation från en fil som inte har verifierats.
Skapa förvaltarnyckeln
Installationens nyckellager förseglar sina återställningsnycklar till en eller flera nyckelförvaltare (custodians). En nyckelförvaltare är en person som förvarar en age-identitetsfil offline, och charten vägrar att installera utan minst en sådan. På nyckelförvaltarens egen maskin:
age-keygen -o custodian.keyFilen börjar med en rad # public key: age1.... Den publika halvan är vad som ska läggas in i värdefilen. Själva identitetsfilen lämnar aldrig nyckelförvaltarens maskin. På en Mac med Secure Enclave skapar age-plugin-se keygen --access-control=any-biometry -o custodian.key en nyckel som kräver Touch ID för att användas, och dess publika halva börjar med age1se1.
Skriv värdefilen
# 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> är age1...-raden från custodian.key. Lägg till en listpost per nyckelförvaltare.
keys.installationName är permanent. Vid den första starten av nyckellagret skapas installationens identitet under det namnet, och ingenting kan byta namn på den i efterhand. Det måste matcha ^[a-z][a-z0-9-]{0,62}$: gemener, börja med en bokstav, högst 63 tecken. Kopiera inte nexus-example eller exempelmottagaren från chartens egna exempelfiler. Charten avvisar båda vid namn, och förkontrollen (preflight) rapporterar samma koder först.
De tre värdnamnen utgör installationens identitet. Varje tjänst vägrar att starta utan dem, och varje inloggning, kaka (cookie) och lösenordsnyckel (passkey) är bunden till hosts.console. Välj namn som ni fortfarande kommer att vilja ha om fem år.
Peka de tre namnen mot servern
Användare når konsolen, API:et (application programming interface) och inloggningstjänsten genom den inbyggda ingress-controllern i k3s, Traefik, på portarna 80 och 443 på servern. Lägg till tre DNS-poster (Domain Name System) för console.harrow.example, api.harrow.example och auth.harrow.example, som var och en pekar på serverns adress. Förkontrollen kontrollerar varje namn och talar om för er vilket som saknar post.
Chartens nätverkspolicy tillåter endast en namnrymd att nå de tre publika tjänsterna. Dess standardvärde, kube-system, är där k3s kör Traefik, så på en enskild nod lämnar ni networkPolicy.ingressNamespace orörd.
Kör förkontrollen och installera sedan
- Kör förkontrollen med flaggan för enskild nod. Den läser av maskinen och er värdefil och ändrar ingenting.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml- Läs sammanfattningsraden på slutet. En varning blockerar aldrig installationen, men det gör ett fel, och varje rad som underkänns innehåller en
fix-rad.
────────────────────────────────────────────────────────────
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
- Installera. Flaggan
--editionmåste stämma överens mededitioni värdefilen.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community- Följ körningen. Den kör förkontrollen igen, installerar k3s v1.33.6+k3s1, installerar cert-manager v1.21.3, installerar Nexus och väntar på att varje tjänst ska svara på sin hälsokontroll. På Tomás server tog det strax under tio minuter.
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
Behåll det fingeravtrycket på skärmen. Ni kommer att jämföra det i webbläsaren när ni gör anspråk på installationen med koden. Om koden hinner gå ut innan ni använder den skapar nexusctl claim-code --administrator <email> en ny. Kapitel 2.12, Den första körningen, tar vid därifrån.
Lägg certifikatet på plats
Med tls.mode: existing presenterar de tre ingress-rutterna certifikatet i den Secret som anges av tls.existingSecret. Det måste täcka alla tre värdnamnen. Förkontrollen läser denna Secret när den finns och varnar när certifikatet löper ut inom 30 dagar. När denna Secret inte finns där ännu uppmanar raden er att skapa den, och det är en varning, inte ett fel.
På en enskild nod existerar inte klustret förrän installationen har skapat det, så skapa denna Secret direkt efter installationen. Skriv först ut klustrets kubeconfig (det sista avsnittet i det här kapitlet förklarar hur), och skapa sedan er Secret med hjälp av den:
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 innehåller certifikatet följt av eventuella mellanliggande certifikat, och harrow-public.key dess privata nyckel. Om era certifikat kommer från en privat CA (certificate authority) tar nexusctl preflight och nexusctl install emot --ca-bundle <file> så att de kan kontrollera kedjan. De andra sätten att hantera TLS (Transport Layer Security) finns i kapitel 2.11, Variationer: externa lager, TLS och ingress.
Om detta misslyckas
| Vad ni ser | Vad det innebär | Vad du ska göra |
|---|---|---|
PREFLIGHT_FAILED (409) |
Förkontrollen hittade ett fel, så installationen startade inte. Ingenting installerades. | Åtgärda varje rad som underkänts med hjälp av dess fix-rad, och kör installationen igen. |
INSTALLATION_NAME_MISSING |
keys.installationName är tom. |
Ange installationens eget permanenta namn. |
INSTALLATION_NAME_EXAMPLE |
Namnet är det som kommer från chartens exempelvärden. | Välj ert eget namn. |
KEYS_CUSTODIAN_MISSING |
keys.custody.recipients är tom. |
Lägg till varje nyckelförvaltares publika age1...-mottagare. |
KEYS_CUSTODIAN_EXAMPLE |
En mottagare är chartens exempelnyckelförvaltare, vars identitet ingen innehar. | Ersätt den med era nyckelförvaltares mottagare. |
nexusctl avslutas med 0 när den kan gå vidare, 1 när en kontroll blockerade den, och 2 när den inte kunde köras alls (en oläsbar värdefil, en felaktig flagga). Ett skript kan förgrena sig baserat på dessa tre.
Del två: en utvärdering på en bärbar dator med k3d
k3d kör k3s inuti Docker-containrar, så ett helt kluster ryms på en bärbar dator och försvinner med ett enda kommando. Utgivningsverktygen som testar varje Nexus-utgåva bygger sina kluster på exakt det här sättet, och genom att kopiera deras inställningar slipper ni återupptäcka de problem som de redan har stött på.
Ni behöver Docker, k3d 5.8.3, kubectl, Helm v4 och Chrome. Tomás använde sin Mac.
Skapa klustret
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.kubeconfigVarje flagga har ett syfte.
--agents 0ger en servernod och inga arbetarnoder (workers). Nexus körs utmärkt på en nod, och en andra nod kostar bara minne.--image rancher/k3s:v1.33.6-k3s1låser den k3s-version som varje utgåva testas på. Utan den får ni vad k3d än har som standard.--disable=traefik@server:0utelämnar Traefik. En bärbar dator har ingen publik adress att betjäna, och ni når konsolen genom er egen HTTPS-front i stället (se nedan).--wait --timeout 300sreturnerar först när klustret svarar, eller avbryter med fel efter fem minuter.
Om ni speglar utgivningsregistret på er bärbara dator, lägg till --registry-config <registries.yaml> för att skicka hämtningar av avbildningar till spegeln, och --k3s-arg "--disable-default-registry-endpoint@server:0" så att ingenting faller tillbaka på ett uppströmsregister. Utgivningsverktygen körs på det här sättet, där varje avbildning enbart kommer via spegeln.
Installera cert-manager
Charten skapar sin egen lokala CA, nexus-local-ca, som en cert-manager-utfärdare (issuer), och varje tjänst får sitt certifikat från den. Utan resurserna från cert-manager i klustret avvisar helm install charten inom några sekunder. Installera cert-manager v1.21.3 först, från den chart som cert-manager-projektet publicerar:
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10mNexus behöver ingenting annat från cert-manager, och i synnerhet ingen trust-manager.
Installera Nexus
- Skriv en värdefil för den bärbara datorn. TLS avslutas vid er egen front, så
tls.modeärnone.
# 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>"- Installera charten från registret och utelämna
--wait(varningen nedan förklarar varför).
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- Vänta sedan in arbetslasterna på egen hand:
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
doneStatefulSet-loopen finns där eftersom vissa av dem uppdaterar en podd i taget på begäran, och kubectl rollout status avvisar dessa. Att vänta på readyReplicas fungerar för alla uppdateringsstrategier.
När båda kommandona returnerar är varje Deployment tillgänglig (Available) och varje StatefulSet har sina poddar redo. Ingen kan logga in ännu. Det är helt i sin ordning: ingen har gjort anspråk på installationen ännu.
Varför en portvidarebefordran aldrig kan logga in er
Det uppenbara nästa steget är kubectl port-forward svc/nexus-alpha 3000:3000 och en webbläsare på http://127.0.0.1:3000. Konsolens sidor laddas, så det ser ut att fungera. Det gör det inte, och ingen inställning kommer att få det att fungera. Tre saker står i vägen, var och en helt avsiktligt.
| Vad som stoppar det | Varför |
|---|---|
| Ursprunget (origin) | Konsolens inloggning avvisar en begäran vars ursprung (origin) inte är https://<hosts.console>, i det här fallet https://console.harrow.example. En sida som levereras från http://127.0.0.1:3000 har fel ursprung, så inloggningen startar aldrig. |
| Kakan (cookie) | Sessionen är en __Host--kaka markerad som Secure. Webbläsare lagrar en sådan kaka endast över HTTPS, utan domänattribut, för exakt den värd som satte den. Över vanlig HTTP kastar webbläsaren bort den. |
| Lösenordsnyckeln (passkey) | Den första administratören loggar in med en lösenordsnyckel (passkey), och en lösenordsnyckel kräver en säker kontext med ett giltigt certifikat. Chrome vägrar att skapa en lösenordsnyckel bakom en certifikatvarning, även om ni har klickat er förbi den. |
Webbläsaren måste alltså tala med https://console.harrow.example, med ett certifikat som den litar på, och det namnet måste leda till er bärbara dator.
Nå konsolen via HTTPS på er bärbara dator
Metoden nedan använder chartens egen CA för att utfärda certifikatet, en portvidarebefordran för att nå konsolen, samt en separat Chrome-profil som litar på just denna CA och mappar konsolens namn till er bärbara dator. Ert systems certifikatförråd och /etc/hosts förblir oförändrade.
Utfärda ett certifikat för konsolens namn
- Be cert-manager om ett certifikat för konsolvärden, signerat av chartens utfärdare:
# 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 signerar det inuti klustret. Ni läser aldrig den privata nyckeln för CA.
- Kopiera ut certifikatet, dess nyckel och CA-certifikatet ur denna 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- Ta fram CA-nyckelns pin-värde. Chrome identifierar en betrodd nyckel genom base64 SHA-256 av dess publika nyckel:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64Lås (pinna) CA-nyckeln, inte certifikatets nyckel. Certifikatet gäller i ett dygn och får en ny nyckel varje gång cert-manager förnyar det, medan CA förblir densamma.
Sätt en HTTPS-front framför en portvidarebefordran
- Vidarebefordra konsolens Service. Dess port är den som heter
http, vilket är 3000 i den här utgåvan:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000- Kör en HTTPS-lyssnare på
127.0.0.1:28443som vidarebefordrar till127.0.0.1:3000. Vilken omvänd proxy som helst som ni redan litar på duger, så länge den gör fyra saker:- presenterar
tls.crtföljt avca.crtsom kedja, medtls.key; - behåller huvudet (headern)
Hostsomconsole.harrow.example; - sätter
X-Forwarded-Proto: https; - släpper igenom WebSocket-uppgraderingar, eftersom konsolen använder dem.
- presenterar
En portvidarebefordran till en Service binder till den enskilda podd som den valde när den startade. Efter att en uppgradering eller en omstart har ersatt konsolpodden ligger vidarebefordran kvar men leder ingenstans, och webbläsaren visar ”bad gateway”. Starta om portvidarebefordran varje gång konsolpodden byts ut.
Öppna Chrome med pin-värdet och namnmappningen
På en 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> är utskriften från openssl-raden. På Linux startar ni Chrome med samma tre flaggor.
De tre flaggorna samverkar. --host-resolver-rules skickar console.harrow.example på port 443 till er front, enbart inuti den här profilen. --ignore-certificate-errors-spki-list litar på certifikat som utfärdats av just denna CA-nyckel, och Chrome respekterar den endast tillsammans med --user-data-dir. Den separata profilen håller undantaget borta från ert dagliga surfande. Det är inte en generell växel som ignorerar alla certifikatfel: allt som inte är signerat av klustrets CA avvisas fortfarande.
Med den profilen öppen leder https://console.harrow.example/install till sidan för att göra anspråk på installationen, och en lösenordsnyckel kan skapas. Kapitel 2.12, Den första körningen, tar vid härifrån.
När den bärbara datorn startar om
Nyckellagret består av två delar: själva nyckellagret och en liten upplåsare (unsealer) som håller dess upplåsningsnyckel. Efter varje omstart av noden (en omstart av Docker, en omstart av datorn, k3d cluster stop och start) startar upplåsaren i förseglat läge. Nyckellagret låser upp sig självt genom den, så tills en nyckelförvaltare låser upp upplåsaren med sin egen age-identitet fungerar ingenting som behöver en nyckel. Det är en egenskap i själva konstruktionen, och det fungerar likadant på ett produktionskluster. Kapitel 2.15, Dag två: drift av Nexus, visar hur upplåsningen går till.
När ni är klara med utvärderingen:
k3d cluster delete harrow-evalAtt ta bort klustret tar bort installationen och allt i den.
nexusctl kubeconfig
Ett kluster som nexusctl install --single-node har byggt tillhör nexusctl. För att nå det med kubectl, helm eller något annat verktyg, begär ut dess kubeconfig:
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulsetFilen ger fullständig administrativ åtkomst till klustret. Håll den i läge (mode) 600, på maskinerna som tillhör de personer som sköter installationen, och ingen annanstans. Varje senare kommando i Del 2 som tar --context eller läser KUBECONFIG fungerar mot en enskild nod genom den här filen. Detsamma gäller vid en uppgradering: nexusctl upgrade plan --bundle <file> och nexusctl upgrade apply --bundle <file> på en enskild nod uppgraderar även det k3s-kluster som nexusctl äger.
nexusctl install --single-node lägger på en Linux-server.Vad som följer med till ett kluster
Allt ni har gjort på en enskild maskin har en motsvarighet i ett kluster. Värdefilen är samma fil med ett annat register, TLS-läge eller lagringsklass (storage class), så som kapitel 2.11, Variationer: externa lager, TLS och ingress, visar. Den första körningen är identisk. Det som inte kan flyttas med är själva installationen: installationsnamnet är låst för gott, och en installation kan inte lyftas från en bärbar dator till en server. När Tomás gick från sin bärbara dator till pilotservern började han om med ett nytt namn, harrow-pilot, och behöll harrow-eval för experiment.
