> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalación Online

> Instala Zylon con acceso completo a internet

Esta guía cubre la instalación estándar de Zylon para entornos con acceso completo a internet. El sistema descargará automáticamente todas las dependencias requeridas, imágenes de contenedores y modelos de IA.

**Lista de Prerrequisitos**:

* [ ] Máquina Linux limpia (Ubuntu 22/24) que cumpla con los [requisitos de hardware](/es/operator-manual/installation/hardware-requirements)
* [ ] Acceso root y SSH a la máquina
* [ ] Un nombre de dominio para Zylon (por ejemplo, zylon.company.com)
* [ ] Capacidad para reiniciar la máquina cuando sea necesario
* [ ] La máquina tiene `curl` instalado

- [ ] Acceso completo y sin restricciones a internet en la máquina objetivo
- [ ] El firewall permite conexiones salientes a registros de Docker y repositorios de paquetes
- [ ] Ya sea:
  * [ ] Puertos 80 y 443 abiertos para la generación automática de certificados SSL de Let's Encrypt, O
  * [ ] Certificado SSL válido listo para configuración manual

***

## Instalando Zylon

<Steps>
  <Step title="Instalar Zylon CLI">
    *Tiempo estimado: 2 min*

    La CLI de Zylon acelerará el tiempo necesario para tener todo listo, se encargará de instalar controladores, actualizar Zylon y configurar el sistema.
    Para instalarla, conéctate por SSH a la máquina donde quieres instalar Zylon y ejecuta:

    ```bash theme={null}
    # ssh <user>@<host-ip>
    sudo curl -sL get.zylon.ai | sh
    ```

    Verifica la instalación:

    ```bash theme={null}
    sudo zylon-cli version
    ```

    <Note>
      Se requiere acceso root para las operaciones de la CLI, ya que gestiona dependencias y configuraciones a nivel de sistema.
    </Note>
  </Step>

  <Step title="Verificar requisitos mínimos de Zylon">
    Asegúrate de que tu máquina cumple con los [requisitos de hardware](/es/operator-manual/installation/hardware-requirements) para Zylon.

    Para validar automáticamente si tu instalación cumple con los requisitos mínimos, ejecuta:

    ```bash theme={null}
    sudo zylon-cli preflight --network --fresh-system -v
    ```

    Resuelve cualquier problema reportado antes de proceder con la instalación. No podrás continuar hasta que todas las comprobaciones previas pasen.

    <Info>
      ¿Tienes problemas con la conectividad de red? Considera cambiar a una [Instalación Semi-Airgap](/es/operator-manual/installation/semi-airgap) o [Instalación Airgap](/es/operator-manual/installation/airgap).
    </Info>

    <Note>
      Zylon requiere que todas las comprobaciones pasen antes de proporcionar soporte de instalación.
    </Note>
  </Step>

  <Step title="Configurar Zylon">
    *Tiempo estimado: 10min*

    Zylon se configura mediante un archivo YAML ubicado en `/etc/zylon/zylon-conf.yaml`.

    **Generar Configuración Inicial**

    Usa la CLI para generar un archivo de configuración inicial:

    ```bash theme={null}
    sudo zylon-cli config init
    ```

    Esto abre un prompt interactivo que te guía a través de las opciones de configuración.

    <Info>
      Si por alguna razón te quedas atascado durante el prompt interactivo, puedes omitirlo añadiendo la bandera `-y` para auto-generar una configuración por defecto:

      ```bash theme={null}
      sudo zylon-cli config init -y
      ```

      Después necesitarás editar manualmente `/etc/zylon/zylon-conf.yaml` para establecer tu configuración deseada basándote en la sección de [configuración manual](#manual-configuration).
    </Info>

    <Tabs>
      <Tab title="Configuración Automática">
        Si ejecutaste `sudo zylon-cli config init`, toda la configuración está establecida.
        Revisa `/etc/zylon/zylon-conf.yaml` para confirmar la configuración. Puedes obtener más información sobre qué configuraciones son requeridas en la sección [Configuración Manual](#manual-configuration).

        <Info>
          Si necesitas volver a ejecutar el asistente de configuración, ejecuta:

          ```bash theme={null}
          sudo zylon-cli config init
          ```
        </Info>

        Puedes
      </Tab>

      <Tab title="Configuración Manual">
        Edita `/etc/zylon/zylon-conf.yaml` para ajustar la configuración según sea necesario.

        **Define tu distribución del sistema operativo**

        Establece `node.distro` para que coincida con tu versión de Ubuntu:

        ```yaml theme={null}
        node:
          distro: "ubuntu22"  # para Ubuntu 22.04
          # distro: "ubuntu24"  # para Ubuntu 24.04
        ```

        **Define tu arquitectura de CPU**

        Establece `node.arch` para que coincida con tu hardware:

        ```yaml theme={null}
        node:
          arch: "amd64"  # para procesadores Intel/AMD
        ```

        **Establece tus controladores de hardware (si aplica)**

        Establece `node.drivers` a `generic` (esta es la única opción soportada):

        ```yaml theme={null}
        node:
          drivers: "generic"
        ```

        **Configura el tipo de clúster**

        Establece `cluster.type` a `k0s` (esta es la única opción soportada para instalaciones de instancia única):

        ```yaml theme={null}
        cluster:
          type: "k0s"
        ```

        **Selecciona tu canal de lanzamiento**

        Establece `channel` a `stable` (recomendado para producción y uso normal) o `unstable` (disponible bajo solicitud para pruebas):

        ```yaml theme={null}
        channel: "stable"
        ```

        **Añade tu información de licencia**

        Establece `license.email` a la dirección de correo electrónico asignada a tu licencia (proporcionada durante el registro).

        Establece `license.id` al ID de licencia compartido contigo por el equipo de Zylon por correo electrónico:

        ```yaml theme={null}
        license:
          email: "champion@company.com"
          id: "2oq..."
        ```

        **Elige tu preset de IA**

        Establece `ai.preset` basándote en tu memoria GPU disponible. Consulta [Presets de IA](/es/operator-manual/ai-presets/getting-started) para más detalles.

        ```yaml theme={null}
        ai:
          preset: "baseline-48g"
        ```

        **Establece tu identificador de empresa**

        Establece `companyIdentifier` a cualquier identificador para el seguimiento anónimo de métricas (por ejemplo, `acme-corp`). Si tienes múltiples instalaciones, usa identificadores diferentes (por ejemplo, `company` y `company-test`):

        ```yaml theme={null}
        companyIdentifier: "tu-empresa"
        ```

        **Desactiva telemetría e informes de errores**

        Para desactivar la telemetría y los informes de errores, añade la siguiente sección:

        ```yaml theme={null}
        observability:
            crashReporting: false
            usageMetrics: false
        ```

        **Configura el ingress de red**

        Establece `ingress.host` al dominio que has preparado para Zylon. Debe ser un nombre de dominio completamente cualificado (FQDN) que apunte a la dirección IP de tu servidor.

        Ejemplos:

        * `zylon.company.com`
        * `ai.acme-corp.com`
        * `zylon-prod.yourcompany.io`

        ```yaml theme={null}
        ingress:
          host: "zylon.tu-empresa.com"
          enabled: true
          tlsEnabled: true
        ```

        **Configura la generación de certificado SSL**

        Si tu servidor es accesible desde internet, Let's Encrypt generará y renovará automáticamente los certificados SSL. Mantén el `certManagerAnnotations` por defecto:

        ```yaml theme={null}
        ingress:
          certManagerAnnotations:
            cert-manager.io/cluster-issuer: "letsencrypt-prod"
        ```

        Si estás en una red privada o necesitas usar un certificado personalizado, consulta [Desactivar Let's Encrypt](#disable-lets-encrypt) a continuación.
      </Tab>
    </Tabs>

    **Ver Configuración Actual**

    ```bash theme={null}
    sudo cat /etc/zylon/zylon-conf.yaml
    ```

    Puedes editar el archivo de configuración directamente usando tu editor de texto preferido (por ejemplo, `nano`, `vim`):

    ```bash theme={null}
    # Elige uno de los siguientes comandos:
    sudo nano /etc/zylon/zylon-conf.yaml
    sudo vim /etc/zylon/zylon-conf.yaml
    ```

    Para información detallada sobre todas las opciones de configuración disponibles, consulta la [Guía de Configuración](/es/operator-manual/configuration/index).
  </Step>

  <Step title="Descargar Modelos de IA">
    *Tiempo estimado: 10min a 1h, dependiendo de la velocidad de red y modelos.*

    **Antes de instalar Zylon**, debes descargar los modelos de IA. Los modelos están determinados por tu configuración de preset de IA.

    Verifica los modelos disponibles y compara con tu preset de IA:

    ```bash theme={null}
    sudo zylon-cli models list
    ```

    Más detalles de preset en la [documentación de Presets de IA](/es/operator-manual/ai-presets/presets).

    Descarga los modelos basados en tu configuración:

    ```bash theme={null}
    sudo zylon-cli models download
    ```

    Esto descargará e instalará los modelos de IA que has especificado en el Wizard.

    Si por alguna razón necesitas descargar modelos específicos, puedes hacerlo con:

    ```bash theme={null}
    sudo zylon-cli models list
    sudo zylon-cli models download model-a model-b model-c
    ```

    Por ejemplo, para el preset `baseline-48g`:

    ```bash theme={null}
    sudo zylon-cli models download qwen/qwen3-14b-awq mixedbread-ai/mxbai-embed-large-v1
    ```
  </Step>

  <Step title="Instalar Zylon">
    *Tiempo estimado: 15min a 1hora, dependiendo del rendimiento del sistema y velocidad de red.*

    Ejecuta el comando de instalación con tu versión deseada:

    ```bash theme={null}
    sudo zylon-cli list-versions
    # Elige tu versión deseada de la lista
    sudo zylon-cli install <version>
    ```

    Reemplaza `<version>` con tu versión objetivo (por ejemplo, `1.50.0`).

    **Qué se Instala**

    El proceso de instalación maneja:

    * Dependencias del sistema (gcc, git, etc.)
    * Distribución de Kubernetes ([k0s](https://k0sproject.io/))
    * Controladores NVIDIA y CUDA (si aplica)
    * Runtime de contenedores y herramientas (kubectl, helm)
    * Imágenes de contenedores de Zylon
    * Generación de certificados SSL (si usas Let's Encrypt)

    <Note>
      Nota que los modelos de IA **no** están incluidos en este paso—fueron instalados en el paso anterior.
    </Note>

    **Monitorear la instalación**

    Supervisa el progreso de la instalación:

    ```bash theme={null}
    # Ver pods de Zylon
    watch sudo k0s kubectl get pods -n zylon

    # Ver validación de GPU (si aplica)
    watch sudo k0s kubectl get pods -n nvidia
    ```

    Espera hasta que todos los pods muestren estado listo `1/1`.

    <Tip>
      **Reinicia después de la instalación** para asegurarte de que los drivers de GPU se carguen correctamente.
    </Tip>

    <Danger>
      **Las actualizaciones del kernel pueden romper los drivers de NVIDIA!**

      Verifica los drivers con: `nvidia-smi`

      Solución de problemas: [Guía de Drivers de NVIDIA](/es/operator-manual/troubleshooting/nvidia-drivers)
    </Danger>

    <Warning>
      Si los servicios permanecen en `ContainerCrashLoopBackOff` durante más de 1 hora, contacta con soporte y comparte los logs.
    </Warning>
  </Step>

  <Step title="Crear Organización">
    *Tiempo estimado: 5 min*

    Después de que Zylon esté instalado y en funcionamiento, crea tu organización y cuenta de administrador root.

    **Prepara la Información**

    Necesitarás:

    * **Nombre de organización**: El nombre de tu empresa o equipo (se puede cambiar más tarde)
    * **Regex de correo electrónico**: Patrón para permitir automáticamente que los usuarios se unan
      * Para correos `name@company.com`, usa: `.*@company\.com`
      * Para SSO (Microsoft Entra, Google), puedes usar: `.*`

    **Ejecuta el Comando Seed**

    ```bash theme={null}
    sudo zylon-cli seed \
      --org-name "Mi Organización" \
      --email-regex ".*@tuempresa\.com"
    ```

    El comando esperará si Zylon no está completamente listo.

    <Danger>
      **Ejecutar el comando seed BORRARÁ TODOS LOS DATOS.** Solo ejecútalo una vez durante la configuración inicial de Zylon.
    </Danger>

    **Credenciales de Inicio de Sesión**

    Después de hacer el seed, obtén la contraseña de un solo uso para la cuenta de administrador:

    ```bash theme={null}
    sudo zylon-cli admin-password
    ```

    Luego inicia sesión con:

    ```
    Usuario: admin@zylon.ai
    Contraseña: [la contraseña de un solo uso impresa arriba]
    ```

    El correo electrónico del administrador root siempre es `admin@zylon.ai` y no se puede cambiar.

    <Note>
      Después del primer inicio de sesión, puedes crear administradores adicionales y configurar la autenticación SSO.
    </Note>
  </Step>

  <Step title="Configurar SSL (Opcional)">
    *Tiempo estimado: 10 min*

    <Info>
      **Omite este paso** si usas certificados automáticos de Let's Encrypt (por defecto para instancias públicas).
    </Info>

    Para despliegues en VPN o nube privada, necesitas instalar manualmente certificados SSL.

    **Eliminar Generación Automática de Certificado**

    Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas:

    ```yaml theme={null}
    certManagerAnnotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
    ```

    **Prepara los Archivos de Certificado**

    Kubernetes requiere que el certificado se divida en dos archivos:

    * `tls.crt` - El archivo de certificado
    * `tls.key` - El archivo de clave privada

    **Convertir desde PFX (si aplica):**

    Si tienes un archivo `.pfx`, conviértelo:

    ```bash theme={null}
    openssl pkcs12 -in <tu-certificado.pfx> -clcerts -nokeys -out tls.crt
    openssl pkcs12 -in <tu-certificado.pfx> -nocerts -out tls.key
    ```

    **Importar Certificado en Kubernetes**

    ```bash theme={null}
    # Elimina cualquier certificado existente
    sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon

    # Importa tu certificado
    sudo k0s kubectl create secret tls zylon-tls \
      --key tls.key \
      --cert tls.crt \
      -n zylon

    # Verifica la creación
    sudo k0s kubectl describe secret zylon-tls -n zylon
    ```

    **Aplicar Cambios**

    Recarga la configuración de Zylon:

    ```bash theme={null}
    sudo zylon-cli sync
    ```

    **Verificar**

    Accede a tu instancia de Zylon en `https://zylon.tu-empresa.com` y confirma:

    * La conexión usa HTTPS
    * El navegador muestra un certificado válido
    * No aparecen advertencias de certificado

    <Tip>
      La renovación del certificado debe hacerse manualmente repitiendo este proceso con archivos de certificado actualizados.
    </Tip>
  </Step>
</Steps>

***

## Actualizando Zylon

Las actualizaciones siguen el mismo proceso que la instalación:

```bash theme={null}
sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli install <new-version>
```

Alternativamente, puedes actualizar directamente a la última versión usando el comando de actualización:

```bash theme={null}
sudo zylon-cli upgrade
```

***

## Migrando a Online

Si tienes una instalación existente de Zylon (semi-airgap o airgap) y quieres migrarla a un entorno completamente online, sigue esta guía. Este proceso preserva tus datos y configuración, mientras realiza la transición a operación online.

<Info>
  **La migración difiere de la instalación nueva:**

  * Tu configuración y datos existentes serán preservados
  * La organización y usuarios ya existen
</Info>

Para migrar una instalación existente de Zylon (Semi-Airgap, o Airgap) a una instalación Online, sigue estos pasos:

1. **Asegurar conectividad**: Verifica que la máquina objetivo tenga acceso completo a internet.
2. **Actualizar configuración**: Ejecuta `sudo zylon-cli config init` para actualizar la configuración para operación online.
3. **Refrescar configuración**: Ejecuta `sudo zylon-cli sync` para aplicar los nuevos ajustes de configuración.
4. **Verificar operación**: Confirma que todos los servicios funcionan correctamente con acceso a internet.

***

## Próximos Pasos

Después de completar la instalación, considera los siguientes próximos pasos para optimizar tu despliegue de Zylon:

* [Configurar Presets de IA](/es/operator-manual/ai-presets) para optimizar según tu hardware
* [Configurar Copias de Seguridad](/es/operator-manual/operations/backup) para protección de datos
* [Revisar Manual de Usuario](/es/user-manual/quick-start-guide) para comenzar