Versión 1.0.0-alpha.1 más reciente
Capítulo 2.8
Instalaciones en una sola máquina
Instale Nexus en un servidor Linux con nexusctl, o evalúelo en un portátil con k3d, y acceda a la consola mediante HTTPS para que funcionen el inicio de sesión y las llaves de acceso (passkeys).
Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

Antes de que Harrow Port Authority pusiera Nexus en su clúster de producción, Tomás Reilly quiso realizar dos instalaciones más pequeñas. Una fue un piloto en un servidor Linux de repuesto en el edificio de operaciones, para las doce personas que lo probarían primero. La otra se ejecutó en su propio portátil, para poder romper cosas sin que nadie se diera cuenta. Este capítulo cubre ambas. Utilizan el mismo chart, las mismas imágenes y la misma primera ejecución que una instalación completa de Kubernetes, por lo que lo que aprenda en una máquina se traslada a la otra.
La vía del servidor es un solo comando: nexusctl install --single-node construye un clúster k3s en la máquina, instala cert-manager y luego instala Nexus. La vía del portátil es más práctica. Usted mismo construye un clúster k3d, instala cert-manager y el chart con Helm, y luego realiza una tarea adicional en la que tropieza casi todo el mundo: pone la consola detrás de HTTPS en su propia máquina, porque un simple reenvío de puertos nunca puede iniciar la sesión de nadie.
Qué tamaño debe tener la máquina
Nexus solicita aproximadamente 2.05 núcleos de CPU (unidad central de procesamiento) y 6.7 GiB de memoria en solicitudes con los valores predeterminados del chart, y sus volúmenes suman 142 GiB. Ese total corresponde a PostgreSQL 50, Valkey 5, Neo4j 20, Qdrant 10, el almacén de objetos 50, los dos almacenes de OpenBao 1 y 5, y el volumen de recibos 1. Las solicitudes son lo que reserva el planificador, y el uso real es mayor una vez que las personas están trabajando.
| Máquina | CPU | Memoria (RAM, memoria de acceso aleatorio) | Disco |
|---|---|---|---|
| Nodo único recomendado | 8 vCPU | 32 GiB | SSD (unidad de estado sólido) de 250 GB |
| Mínimo para evaluación | 4 vCPU | 16 GiB | 200 GB |
Un portátil que cumpla con el mínimo de evaluación ejecutará Nexus, pero cuenta el límite de memoria propio de Docker, no el del portátil. Asigne a Docker al menos 16 GiB antes de comenzar.
Ambas vías necesitan Kubernetes 1.33 o posterior. La vía de nodo único trae el suyo propio: k3s v1.33.6+k3s1, la distribución en la que se prueba cada versión.
Primera parte: un servidor Linux con nexusctl
El servidor piloto de Tomás es una máquina de 8 núcleos con 32 GiB de memoria y un SSD de 500 GB, que ejecuta un Linux actual sin nada más instalado. La instalación necesita permisos de root, porque instala k3s como un servicio del sistema.
Obtener nexusctl y verificarlo
- Descargue
nexusctlpara su arquitectura desdehttps://downloads.adverant.ai/nexus/1.0.0-alpha.1/, junto con la clave pública de la versión. Guarde la clave comorelease.pub. El capítulo 2.4, Obtención y verificación de una versión, explica cómo comprobar la huella digital de la clave con la que publica Adverant. - Verifique el binario y la versión con la clave:
nexusctl version --json
nexusctl verifynexusctl verify comprueba la descarga contra la clave de versión de Adverant y rechaza cualquier cosa que no pueda verificar. Si falla, deténgase y descargue de nuevo. Nunca ejecute una instalación desde un archivo que no se haya verificado.
Crear la clave de custodio
El almacén de claves de la instalación sella sus claves de recuperación para uno o más custodios. Un custodio es una persona que posee un archivo de identidad age fuera de línea, y el chart se niega a instalarse sin al menos uno. En la propia máquina del custodio:
age-keygen -o custodian.keyEl archivo comienza con una línea # public key: age1.... Esa mitad pública es lo que va en el archivo de valores. El archivo de identidad en sí nunca sale de la máquina del custodio. En un Mac con Secure Enclave, age-plugin-se keygen --access-control=any-biometry -o custodian.key crea una clave que necesita Touch ID para usarse, y su mitad pública comienza con age1se1.
Escribir el archivo de valores
# 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> es la línea age1... de custodian.key. Añada una entrada de lista por cada custodio.
keys.installationName es permanente. El primer inicio del almacén de claves acuña la identidad de la instalación bajo ese nombre, y nada lo cambia después. Debe coincidir con ^[a-z][a-z0-9-]{0,62}$: minúsculas, comenzando con una letra, como máximo 63 caracteres. No copie nexus-example ni el destinatario de ejemplo de los propios archivos de ejemplo del chart. El chart rechaza ambos por su nombre, y la comprobación previa informa primero de los mismos códigos.
Los tres hosts son la identidad de la instalación. Todos los servicios se niegan a iniciarse sin ellos, y cada inicio de sesión, cookie y passkey está vinculado a hosts.console. Elija nombres que aún quiera conservar dentro de cinco años.
Apuntar los tres nombres al servidor
Los usuarios llegan a la consola, a la API (interfaz de programación de aplicaciones) y al servicio de inicio de sesión a través del controlador ingress integrado de k3s, Traefik, en los puertos 80 y 443 del servidor. Añada tres registros DNS (sistema de nombres de dominio) para console.harrow.example, api.harrow.example y auth.harrow.example, cada uno apuntando a la dirección del servidor. La comprobación previa verifica cada nombre y le indica cuál no tiene registro.
La política de red del chart permite que solo un espacio de nombres llegue a los tres servicios públicos. Su valor predeterminado, kube-system, es donde k3s ejecuta Traefik, por lo que en un nodo único se deja networkPolicy.ingressNamespace sin tocar.
Ejecutar la comprobación previa y luego instalar
- Ejecute la comprobación previa con el indicador de nodo único. Lee la máquina y su archivo de valores y no cambia nada.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml- Lea la línea de resumen al final. Una advertencia nunca bloquea la instalación, pero un fallo sí, y cada fila con fallo incluye una línea
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
- Instale. El indicador
--editiondebe coincidir coneditionen el archivo de valores.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community- Observe cómo se ejecuta. Ejecuta la comprobación previa de nuevo, instala k3s v1.33.6+k3s1, instala cert-manager v1.21.3, instala Nexus y espera a que cada servicio responda a su comprobación de estado. En el servidor de Tomás tardó algo menos de diez minutos.
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
Mantenga esa huella digital en pantalla. La comparará en el navegador cuando reclame la instalación con el código. Si el código caduca antes de que lo use, nexusctl claim-code --administrator <email> genera uno nuevo. El capítulo 2.12, La primera ejecución, continúa a partir de ahí.
Colocar el certificado en su lugar
Con tls.mode: existing, las tres rutas de ingress sirven el certificado en el Secret nombrado por tls.existingSecret. Tiene que cubrir los tres hosts. La comprobación previa lee ese Secret cuando existe y advierte cuando el certificado vence en menos de 30 días. Cuando el Secret aún no está ahí, la fila le indica que lo cree, y es una advertencia, no un fallo.
En un nodo único, el clúster no existe hasta que la instalación lo ha creado, así que cree el Secret inmediatamente después de la instalación. Escriba primero el kubeconfig del clúster (la última sección de este capítulo lo explica) y luego cree el Secret con él:
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 contiene el certificado seguido de cualquier certificado intermedio, y harrow-public.key su clave privada. Si sus certificados provienen de una CA (autoridad de certificación) privada, nexusctl preflight y nexusctl install toman --ca-bundle <file> para poder comprobar la cadena. Las otras formas de manejar TLS (seguridad de la capa de transporte) están en el capítulo 2.11, Variaciones: almacenes externos, TLS e ingress.
Si esto falla
| Lo que ve | Qué significa | Qué hacer |
|---|---|---|
PREFLIGHT_FAILED (409) |
La comprobación previa encontró un fallo, por lo que la instalación no se inició. No se instaló nada. | Corrija cada fila con fallo, utilizando su línea fix, y ejecute la instalación de nuevo. |
INSTALLATION_NAME_MISSING |
keys.installationName está vacío. |
Establezca el nombre permanente propio de la instalación. |
INSTALLATION_NAME_EXAMPLE |
El nombre es el de los valores de ejemplo del chart. | Elija su propio nombre. |
KEYS_CUSTODIAN_MISSING |
keys.custody.recipients está vacío. |
Añada el destinatario age1... público de cada custodio. |
KEYS_CUSTODIAN_EXAMPLE |
Un destinatario es el custodio de ejemplo del chart, cuya identidad nadie posee. | Reemplácelo con los destinatarios de sus custodios. |
nexusctl sale con 0 cuando puede continuar, con 1 cuando una comprobación lo bloqueó y con 2 cuando no pudo ejecutarse en absoluto (un archivo de valores ilegible, un indicador incorrecto). Un script puede bifurcarse en función de esos tres valores.
Segunda parte: una evaluación en un portátil con k3d
k3d ejecuta k3s dentro de contenedores Docker, por lo que un clúster entero vive en un portátil y desaparece con un solo comando. Las herramientas de lanzamiento que prueban cada versión de Nexus construyen sus clústeres exactamente de esta manera, y copiar su configuración le ahorra redescubrir los problemas que ellas ya encontraron.
Necesita Docker, k3d 5.8.3, kubectl, Helm v4 y Chrome. Tomás usó su Mac.
Crear el clúster
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.kubeconfigCada indicador tiene una razón.
--agents 0proporciona un nodo servidor y ningún nodo trabajador. Nexus se ejecuta sin problemas en un nodo, y un segundo nodo solo consume memoria.--image rancher/k3s:v1.33.6-k3s1fija la versión de k3s en la que se prueba cada lanzamiento. Sin él, obtiene la versión predeterminada de k3d.--disable=traefik@server:0omite Traefik. Un portátil no tiene una dirección pública que servir, y en su lugar usted llega a la consola a través de su propio frontal HTTPS (más abajo).--wait --timeout 300sregresa solo cuando el clúster responde, o falla después de cinco minutos.
Si replica el registro de versiones en su portátil, añada --registry-config <registries.yaml> para enviar las descargas de imágenes al espejo, y --k3s-arg "--disable-default-registry-endpoint@server:0" para que nada recurra a un registro de origen. Las herramientas de lanzamiento se ejecutan de esta manera, con cada imagen proveniente únicamente a través del espejo.
Instalar cert-manager
El chart crea su propia CA local, nexus-local-ca, como un emisor de cert-manager, y cada servicio obtiene su certificado de ella. Sin los recursos de cert-manager en el clúster, helm install rechaza el chart en cuestión de segundos. Instale primero cert-manager v1.21.3, desde el chart que publica el proyecto cert-manager:
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10mNexus no necesita nada más de cert-manager, y en particular ningún trust-manager.
Instalar Nexus
- Escriba un archivo de valores para el portátil. TLS termina en su propio frontal, por lo que
tls.modeesnone.
# 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>"- Instale el chart desde el registro y omita
--wait(la advertencia a continuación explica por qué).
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- Luego espere a las cargas de trabajo usted mismo:
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
doneEl bucle de StatefulSet está ahí porque algunos de ellos actualizan un pod a la vez bajo petición, y kubectl rollout status los rechaza. Esperar a readyReplicas funciona para cualquier estrategia de actualización.
Cuando ambos comandos regresan, cada Deployment está Available y cada StatefulSet tiene sus pods listos. Nadie puede iniciar sesión todavía. Eso es correcto: la instalación no ha sido reclamada.
Por qué un reenvío de puertos nunca permite iniciar sesión
El siguiente paso obvio es kubectl port-forward svc/nexus-alpha 3000:3000 y abrir un navegador en http://127.0.0.1:3000. Las páginas de la consola se cargan, por lo que parece que funciona. No es así, y ningún ajuste hará que funcione. Tres cosas se interponen en el camino, cada una a propósito.
| Qué lo detiene | Por qué |
|---|---|
| El origen | El inicio de sesión de la consola rechaza una solicitud cuyo origen no sea https://<hosts.console>, aquí https://console.harrow.example. Una página servida desde http://127.0.0.1:3000 tiene el origen incorrecto, por lo que el inicio de sesión nunca comienza. |
| La cookie | La sesión es una cookie __Host- marcada como Secure. Los navegadores almacenan dicha cookie solo a través de HTTPS, sin atributo de dominio, exactamente para el host que la estableció. A través de HTTP simple, el navegador la descarta. |
| La passkey | El primer administrador inicia sesión con una passkey, y una passkey necesita un contexto seguro con un certificado válido. Chrome se niega a crear una passkey detrás de una advertencia de certificado, incluso si usted hizo clic para ignorarla. |
Por lo tanto, el navegador tiene que hablar con https://console.harrow.example, con un certificado en el que confíe, y ese nombre tiene que dirigir a su portátil.
Acceder a la consola mediante HTTPS en su portátil
El método a continuación utiliza la propia CA del chart para emitir el certificado, un reenvío de puertos para llegar a la consola y un perfil separado de Chrome que confía en esa única CA y asigna el nombre de la consola a su portátil. El almacén de confianza de su sistema y /etc/hosts permanecen como están.
Emitir un certificado para el nombre de la consola
- Pida a cert-manager un certificado para el host de la consola, firmado por el emisor del 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 lo firma dentro del clúster. Usted nunca lee la clave privada de la CA.
- Copie el certificado, su clave y el certificado de la CA fuera del 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- Calcule el pin de la CA. Chrome identifica una clave de confianza mediante el SHA-256 en base64 de su clave pública:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64Fije la clave de la CA, no la del certificado. El certificado dura un día y obtiene una clave nueva cada vez que cert-manager lo renueva, mientras que la CA sigue siendo la misma.
Poner un frontal HTTPS delante de un reenvío de puertos
- Reenvíe el Service de la consola. Su puerto es el llamado
http, que es el 3000 en esta versión:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000- Ejecute un receptor HTTPS en
127.0.0.1:28443que reenvíe a127.0.0.1:3000. Cualquier proxy inverso en el que ya confíe servirá, siempre que haga cuatro cosas:- sirva
tls.crtseguido deca.crtcomo la cadena, contls.key; - mantenga el encabezado
Hostcomoconsole.harrow.example; - establezca
X-Forwarded-Proto: https; - deje pasar las actualizaciones de WebSocket, porque la consola las utiliza.
- sirva
Un reenvío de puertos a un Service se vincula al único pod que eligió cuando se inició. Después de que una actualización o un reinicio reemplace el pod de la consola, el reenvío permanece activo pero no reenvía a nada, y el navegador muestra un error de puerta de enlace incorrecta (bad gateway). Reinicie el reenvío de puertos cada vez que cambie el pod de la consola.
Abrir Chrome con el pin y la asignación de nombres
En 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> es la salida de la línea openssl. En Linux, inicie Chrome con los mismos tres indicadores.
Los tres indicadores funcionan juntos. --host-resolver-rules envía console.harrow.example en el puerto 443 a su frontal, solo dentro de este perfil. --ignore-certificate-errors-spki-list confía en los certificados emitidos por esa única clave de CA, y Chrome lo respeta solo con --user-data-dir. El perfil separado mantiene la excepción alejada de su navegación diaria. No es un interruptor general para "ignorar errores de certificado": cualquier cosa que no esté firmada por la CA del clúster seguirá fallando.
Con ese perfil abierto, https://console.harrow.example/install lleva a la página de reclamación y se puede crear una passkey. El capítulo 2.12, La primera ejecución, continúa a partir de aquí.
Cuando el portátil se reinicia
El almacén de claves tiene dos partes: el propio almacén de claves y un pequeño abridor (unsealer) que contiene su clave de desbloqueo. Después de cualquier reinicio del nodo (un reinicio de Docker, un reinicio del portátil, k3d cluster stop y start) el abridor se inicia sellado. El almacén de claves se abre a sí mismo a través de él, por lo que hasta que un custodio abra el abridor con su propia identidad age, nada que necesite una clave funcionará. Esa es una propiedad del diseño, y es igual en un clúster de producción. El capítulo 2.15, Día dos: operación de Nexus, muestra el proceso de apertura.
Cuando haya terminado con la evaluación:
k3d cluster delete harrow-evalEliminar el clúster elimina la instalación y todo lo que contiene.
nexusctl kubeconfig
Un clúster construido por nexusctl install --single-node pertenece a nexusctl. Para llegar a él con kubectl, helm o cualquier otra herramienta, solicite su kubeconfig:
sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulsetEl archivo otorga acceso administrativo completo al clúster. Manténgalo en modo 600, en las máquinas de las personas que administran la instalación, y en ningún otro lugar. Cada comando posterior en la Parte 2 que toma --context o lee KUBECONFIG funciona contra un nodo único a través de este archivo. Lo mismo se aplica a una actualización: nexusctl upgrade plan --bundle <file> y nexusctl upgrade apply --bundle <file> en un nodo único también actualizan el clúster k3s que posee nexusctl.
nexusctl install --single-node instala en un servidor Linux.Qué se conserva al pasar a un clúster
Todo lo que hizo en una máquina tiene un equivalente en un clúster. El archivo de valores es el mismo archivo con un registro, modo TLS o clase de almacenamiento diferente, como muestra el capítulo 2.11, Variaciones: almacenes externos, TLS e ingress. La primera ejecución es idéntica. Lo que no se traslada es la instalación en sí: el nombre de la instalación queda fijado para siempre, y una instalación no se puede trasladar de un portátil a un servidor. Cuando Tomás pasó de su portátil al servidor piloto, comenzó de nuevo con un nombre nuevo, harrow-pilot, y mantuvo harrow-eval para experimentos.
