Autoalojamiento

Guía de despliegue (paso a paso)

Un recorrido paso a paso para desplegar Keyright autoalojado en tu propio entorno: requisitos previos, obtener el kit de despliegue, generar secretos, preparar PostgreSQL, elegir una ruta de despliegue (Docker Compose, Kubernetes/Helm o Windows/IIS), instalar tu licencia, verificar e iniciar sesión — de cero a una instancia en marcha y licenciada.

Esta es la guía lineal, de haz-esto-luego-aquello, para una instancia en marcha. Da por hecho que has echado un vistazo a la visión general de la arquitectura. Cada ajuste que toca tiene una referencia completa en Configuración; cuando un paso necesita más profundidad, enlaza allí.

Al final tendrás una instancia de Keyright licenciada respondiendo a /health, un panel con sesión iniciada y la URL base exacta a la que apuntará el SDK de tu producto.

Paso 0 — Comprueba los requisitos previos

Un runtime de contenedores (recomendado): Docker 24+ con Compose v2, o Kubernetes 1.24+ con Helm 3. O Windows/IIS con el .NET 8 Hosting Bundle (Paso 4C, sin contenedores).
PostgreSQL 14+ (16 recomendado), UTF-8. Para una primera evaluación puedes dejar que el paquete ejecute uno por ti (Paso 3); para producción, prepara tu propio Postgres gestionado/HA.
Una licencia o clave de prueba de Keyright de Delta1 — necesaria para ejecutar. Contacta con ventas para una prueba Enterprise de 30 días o una licencia de pago Standard/Enterprise. Guarda la clave que recibas como license.json.
openssl en la máquina desde la que ejecutas estos pasos (para generar secretos en el Paso 2).

Paso 1 — Obtén el kit de despliegue

La imagen de contenedor es pública — descárgala sin autenticación (fija la versión para una instalación reproducible):

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

El kit de despliegue — los archivos de configuración que el resto de esta guía referencia — te lo envía Delta1 con tu licencia (o bajo petición desde ventas). Contiene:

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

Descomprímelo en un directorio de trabajo; los comandos de abajo se ejecutan desde ahí.

Paso 2 — Genera tus secretos

Keyright necesita tres secretos que creas y conservas. Genéralos ahora:

openssl rand -hex 24                                                            # KEYRIGHT_ADMIN_TOKEN  (your root admin credential)
openssl rand -base64 32                                                         # KEYRIGHT_KEK          (encrypts signing keys at rest — 32 bytes)
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform DER | base64 -w0   # KEYRIGHT_SIGNING_KEY  (optional; signs offline leases)

(En macOS/BSD, base64 no tiene -w0; usa ... -outform DER | base64 | tr -d '\n'.)

Haz copia de seguridad de la KEK y de la clave de firma por separado y de forma segura. Son tuyas — nosotros nunca las vemos — y sin la KEK, las claves de firma cifradas en tu base de datos no pueden recuperarse. La clave de firma es opcional (Keyright genera una por inquilino en la BD si la omites), pero si la estableces, haz copia de seguridad de ella también.

El significado completo de cada variable está en Configuración.

Paso 3 — Prepara la base de datos

Tú proporcionas un servidor PostgreSQL y una base de datos vacía; Keyright construye el esquema por sí mismo en el primer arranque — no hay archivo .sql ni SQL que ejecutar a mano. Las migraciones están compiladas en la imagen y se aplican automáticamente en cada arranque (db.Database.Migrate()).

Producción — tu propio Postgres. Crea una base de datos vacía y un rol de login, y haz que el rol sea el propietario de la base de datos (la configuración correcta más simple — la aplicación debe poder ejecutar CREATE/ALTER/DROP para aplicar migraciones):

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

En PostgreSQL 15+, si el rol no es el propietario, añade también GRANT ALL ON SCHEMA public TO keyright_app;. Algunos proveedores gestionados (Azure Flexible Server, Cloud SQL) no permiten CREATE DATABASE por SQL — crea la base de datos vacía + el rol desde su consola/CLI, y luego otorga permisos como se indica arriba. AWS RDS/Aurora, Cloud SQL, Azure, Neon, Supabase funcionan todos. Luego construye tu cadena de conexión (formato Npgsql, TLS obligatorio):

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

Esa cadena es tu KEYRIGHT_DB. Consulta Configuración → Base de datos para las opciones de TLS y las notas sobre proveedores gestionados.

Evaluación — sáltate este paso. Docker Compose y el chart de Helm pueden arrancar un postgres:16 por ti con la base de datos y el rol precreados. Está bien para una primera ejecución e instalaciones pequeñas de un solo nodo; pasa a tu propio Postgres gestionado/HA para producción.

Paso 4 — Despliega

Elige la ruta que coincida con tu entorno. Las tres producen el mismo servicio en marcha.

Paso 4A — Docker Compose (un solo nodo)

La forma más rápida de llegar a una instancia en marcha — Postgres + la aplicación en un solo host:

cp deploy/.env.example deploy/.env        # then fill in the secrets from Step 2 (and KEYRIGHT_DB for production)
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d

Establece tu licencia en deploy/.env como KEYRIGHT_SELF_LICENSE (el JSON de la licencia en una sola línea) o monta un archivo y establece KEYRIGHT_SELF_LICENSE_FILE (el kit tiene un ejemplo comentado de volumes:). Fija una versión con KEYRIGHT_VERSION. Para producción establece un KEYRIGHT_DB real en lugar del Postgres incluido.

Paso 4B — Kubernetes (Helm)

Guarda tu licencia en license.json y pásala con --set-file — no uses --set/--set-string para la licencia ni para la cadena de la BD: ambas contienen comas/llaves que el parser de --set de Helm divide, lo que falla con key "…" has no value.

Producción — tu propio Postgres externo (recomendado):

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

Evaluación — Postgres incluido dentro del clúster (quita las dos líneas de BD de arriba y mantén el valor por defecto):

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

Fija la versión de la imagen. Añade --set image.tag=<version> (p. ej. --set image.tag=2.2.2) para un despliegue reproducible. Sin establecer, se usa por defecto el appVersion del chart.

¿Límites de tasa de Docker Hub? El Postgres incluido descarga postgres:16 de Docker Hub, que limita la tasa de descargas anónimas. Si el pod postgres se queda atascado en ImagePullBackOff, apúntalo a tu propio registro/espejo con --set postgres.image=<registry>/postgres:16 (consulta Configuración → Valores de Kubernetes).

Espera unos cuantos reinicios en el primer arranque con Postgres incluido. Keyright ejecuta sus migraciones al arrancar, y el Postgres incluido tarda un momento en estar Ready — así que en una instalación de evaluación nueva el pod de la aplicación puede entrar en CrashLoopBackOff unas cuantas veces mientras espera a la BD. Esto es esperado, no un error; se resuelve en un minuto o dos una vez que Postgres está Ready. Con un Postgres externo, un bucle de caída persistente significa en cambio que la BD realmente no es accesible (consulta Operaciones → Resolución de problemas).

secrets.adminToken y secrets.kek son obligatorios — el chart se niega a renderizar sin ellos. Consulta Configuración → Kubernetes para ingress, réplicas, recursos, marca blanca, la sustitución de la imagen incluida y cómo llegar al servicio con un port-forward.

Paso 4C — Windows / IIS

Para equipos que no ejecutarán contenedores:

pwsh deploy/windows/build-win-bundle.ps1        # add -SelfContained if the server has no .NET 8

Descomprime .artifacts/keyright-win/keyright-issuing-win-x64.zip en la ruta física de un sitio de IIS. El web.config incluido conecta el ASP.NET Core Module (in-process). Establece los valores KEYRIGHT_* como variables de entorno de máquina (preferido) o en web.config, instala el .NET 8 Hosting Bundle e inicia el sitio. Apunta KEYRIGHT_DB a tu PostgreSQL.

Paso 5 — Verifica

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 es liveness; /health/ready también comprueba la base de datos. /admin/self-license informa de tu edición, phase (active / expiring / grace / gated), días restantes y si el runtime está bloqueado — si dice gated, tu licencia no se cargó (consulta Licenciamiento).

Tu URL base. Para una ejecución local/de evaluación es http://localhost:<KEYRIGHT_PORT> (por defecto http://localhost:8080); en producción es el host que sirva tu balanceador de carga (p. ej. https://licensing.acme.example). Cada curl y cada ServiceUrl del SDK de aquí en adelante usa esa base.

En Kubernetes sin un ingress, llega al servicio con un port-forward. El servicio se llama <release>-keyright — para el release keyright usado arriba eso es keyright-keyright:

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

Paso 6 — Inicia sesión en el panel

Abre <base>/dashboard. En una instancia nueva aún no tienes ningún usuario del panel — inicia sesión con tu token de administración: expande “Advanced: use an access token”, pega tu KEYRIGHT_ADMIN_TOKEN y luego View dashboard. (El inicio de sesión con correo/contraseña necesita un usuario aprovisionado mediante POST /admin/team/{id}/set-password; SSO es la opción Enterprise KEYRIGHT_SSO_*.) El token de administración es tu credencial de root — trátalo en consecuencia.

Está en marcha — qué sigue

Conecta tu producto a tu instancia — crea un producto, genera su clave de firma, apunta el SDK de tu aplicación a tu URL base y emite tu primera licencia. Este es el paso que hace real el autoalojamiento.
Licenciamiento y ediciones — cómo tu propia clave delimita la instancia, la prueba y las renovaciones.
Operaciones y resolución de problemas — escalado, copias de seguridad, actualizaciones, aislado y la solución para lo que no haya salido en verde arriba.

¿Atascado en un paso? Habla con ventas/soporte — te ayudaremos a ponerlo en marcha.