Instalación

Zeltro funciona en Linux y macOS, y en Windows mediante la app de escritorio, que configura Zeltro dentro de WSL2 por ti (consulta Windows más abajo).

Ejecuta cada instalador con tu usuario normal, no como root. Te pide tu contraseña de sudo cuando la necesita.

Instalación con una sola línea#

Estas líneas instalan solo la CLI. Si también quieres la app de escritorio, usa en su lugar las líneas de La app de escritorio, que además instalan la CLI si te falta.

Plataforma Comando
Ubuntu 22.04 / 24.04 / 26.04, y distribuciones basadas en Ubuntu (Linux Mint, Pop!_OS) curl -fsSL https://dist.canebaycomputers.com/zeltro/cli/ubuntu | bash
Fedora 43 / 44 curl -fsSL https://dist.canebaycomputers.com/zeltro/cli/fedora | bash
Arch Linux curl -fsSL https://dist.canebaycomputers.com/zeltro/cli/arch | bash
macOS curl -fsSL https://dist.canebaycomputers.com/zeltro/cli/mac | bash

Cada enlace corto redirige al install-<os>.sh correspondiente del repositorio zeltro-cli.

Debian en sí, RHEL, Rocky y Alma todavía no son compatibles. El instalador de Ubuntu usa el repositorio de paquetes de Docker para Ubuntu, y el de Fedora usa el repositorio de Docker para Fedora. Ninguno de los dos tiene paquetes para esas distribuciones.

Después de instalar, en Linux, cierra sesión y vuelve a entrar (consulta Todas las distribuciones Linux). Luego ejecuta esto una vez:

zeltro configure

Cada instalador configura Docker, Node.js (mediante nvm, si todavía no tienes Node 16 o posterior), Git, jq, un comando trash, ImageMagick, rsvg-convert y la CLI de GitHub. Después clona Zeltro en /usr/local/share/zeltro-cli y enlaza el comando zeltro en /usr/local/bin. En macOS también instala las Xcode Command Line Tools, Homebrew y Docker Desktop si falta alguno.

zeltro configure hace lo siguiente:

  • escribe /etc/zeltro-cli/.env
  • elige una subred privada de Docker
  • crea tu directorio de proyectos (~/zeltro-projects de forma predeterminada)
  • configura tu nombre y correo de Git si todavía no lo están
  • instala el autocompletado con tabulador de bash
  • arranca los servicios compartidos

Notas por plataforma#

Todas las distribuciones Linux#

El instalador te agrega al grupo docker. Cierra sesión y vuelve a entrar (o reinicia) antes de usar Zeltro, o se rechazarán las llamadas a Docker. Por SSH basta con volver a conectarte.

macOS#

El instalador instala Docker Desktop. Ábrelo una vez y acepta su licencia. Docker Desktop es gratis para uso personal, educación y pequeñas empresas; las empresas más grandes necesitan una suscripción de pago de Docker (condiciones de Docker). Docker Desktop tiene que estar en ejecución siempre que uses Zeltro. Es compatible con la versión actual de macOS y las dos anteriores.

Docker Desktop mantiene los contenedores dentro de una máquina virtual, así que la IP del contenedor no es accesible desde el Mac. En su lugar, zeltro status muestra una dirección http://localhost:<port> para cada proyecto.

Arch#

pacman -Syu hace una actualización completa del sistema, que a menudo reemplaza el kernel en uso. Cuando eso pasa, Docker no puede arrancar hasta que reinicies. El instalador lo detecta y muestra un paso REBOOT NOW. Reinicia y vuelve a ejecutar el instalador para terminar.

Fedora: SELinux#

Fedora ejecuta SELinux en modo enforcing, y Zeltro monta el directorio de cada proyecto dentro de su contenedor (bind mount).

Docker CE desactiva el confinamiento de SELinux de forma predeterminada (los contenedores se ejecutan sin confinar como spc_t), así que una instalación estándar no se ve afectada. Una vez que activas la compatibilidad de Docker con SELinux ("selinux-enabled": true en /etc/docker/daemon.json), un directorio de proyecto sin etiquetar hace que todos los contenedores den Permission denied.

zeltro configure etiqueta tu directorio de proyectos como container_file_t, así que Zeltro funciona en ambos casos. Si mueves tu directorio de proyectos a mano, vuelve a ejecutar zeltro configure para etiquetarlo de nuevo.

Windows#

Descarga la app de escritorio desde zeltro.ai/download/windows (un .exe de instalación en beta; consulta Descargas). Zeltro en sí se ejecuta en Linux, así que en Windows funciona dentro de WSL2, y la app lo configura por ti:

  1. El instalador pide permisos de administrador una vez. Windows muestra su aviso habitual de "permitir que esta aplicación haga cambios". Con ese permiso, el instalador activa las características de Windows que necesita WSL2 (WSL y Plataforma de máquina virtual) y actualiza WSL. Si Windows necesita reiniciar para esas características, la última página del instalador te lo indica.
  2. La app hace el resto la primera vez que la abres, sin más avisos de administrador. Instala Ubuntu 24.04 en WSL2, e instala y configura Zeltro dentro. No necesitas escribir nada en una terminal.

Las actualizaciones de la app se saltan el paso de administrador. Si prefieres tener tus proyectos en otro equipo, la app también puede controlar Zeltro en un equipo Linux o en un Mac por SSH (consulta Descargas).

También hay un script de CLI más antiguo, install-windows.ps1, que hace la misma configuración desde una terminal. Se retirará ahora que la app de escritorio lo hace. Necesita una PowerShell abierta con Ejecutar como administrador:

irm https://raw.githubusercontent.com/CaneBayComputers/zeltro-cli/master/install-windows.ps1 | iex

El script se ejecuta en dos etapas, porque activar las características de Windows para WSL requiere reiniciar. Se programa a sí mismo para continuar cuando vuelvas a iniciar sesión. Necesita Windows 10 versión 2004 (compilación 19041) o posterior, o Windows 11, y rechaza las compilaciones más antiguas antes de cambiar nada. Coincide con el mínimo que Microsoft indica para wsl --install.

WSL2 necesita virtualización por hardware: VT-x/AMD-V activado en la BIOS/UEFI, además de SLAT. Si está desactivada, la app te lo indica y te muestra cómo activarla en la configuración de BIOS/UEFI de tu equipo. (Con el script, la descarga de Ubuntu se completa y luego su registro falla con HCS_E_HYPERV_NOT_INSTALLED). Por eso tampoco se puede ejecutar dentro de una máquina virtual de VirtualBox, ya que VirtualBox no le pasa SLAT al sistema invitado.

Hay dos cosas que se comportan distinto en WSL:

  • WSL apaga una distribución inactiva y detiene sus contenedores con ella. Mantén una terminal abierta, o ejecuta wsl -d Ubuntu-24.04 -u root -e sleep infinity.
  • Abre los proyectos con la dirección LAN ACCESS que muestra zeltro status. Es la dirección de la máquina virtual de WSL y cambia cuando WSL se reinicia, así que consúltala en el estado cada vez en lugar de guardarla en marcadores.

Instalar desde una copia local#

Usa esto si quieres trabajar en el propio Zeltro. Cuando ejecutas un instalador desde dentro de una copia local del repositorio, se salta el git clone y crea un enlace simbólico de /usr/local/share/zeltro-cli a tu carpeta.

git clone https://github.com/CaneBayComputers/zeltro-cli.git
cd zeltro-cli
./install-ubuntu.sh      # or install-fedora.sh / install-arch.sh / install-mac.sh

Configuración#

Puedes volver a ejecutar zeltro configure sin problema. Toma los valores que ya hay en /etc/zeltro-cli/.env como predeterminados.

Opción Descripción
--git-name <name> Nombre de usuario de Git
--git-email <email> Correo de usuario de Git
--projects-dir <dir> Directorio de proyectos (predeterminado: el existente, o ~/zeltro-projects)
--vpc-subnet <A.B.C> Subred de la VPC de Docker (predeterminado: la existente, o un 10.x.x aleatorio)
--non-interactive, -y No pregunta nada; acepta los valores predeterminados de todo lo que no pases como opción

Para una configuración totalmente desatendida, como en un script, en CI o al preparar un equipo para un agente:

zeltro configure --non-interactive \
  --git-name "Your Name" --git-email "you@example.com"

Zeltro no pide credenciales de AWS ni autenticación de GitHub, y no necesita ninguna de las dos. Nada en Zeltro usa AWS. Solo necesitas autenticarte en GitHub para las opciones --github, que son opcionales, y para clone fork y clone new-repo. Si los usas sin autenticarte, en ese momento te indican que ejecutes gh auth login.

Zeltro elige la subred de la VPC de Docker por ti. Es una /24 privada en el rango 10.x.x, nunca 10.0.x, así que no puede chocar con la red 10.0.0.0/24 que usan muchas redes domésticas y de oficina. Usa --vpc-subnet si necesitas un rango concreto.

El autocompletado con tabulador cubre comandos, nombres de proyectos, nombres de frameworks y nombres de instaladores:

zeltro ins<TAB>            → install
zeltro install gr<TAB>     → grafana  gramps-web  graylog  grist  grocy
zeltro up <TAB>            → (your project names)
zeltro new <TAB>           → django  express  fastapi  flask  kavera  laravel  ...

La app de escritorio#

La app de escritorio de Zeltro es opcional. En Linux, un solo comando la instala, e instala antes esta CLI si falta zeltro:

curl -fsSL https://dist.canebaycomputers.com/zeltro/ubuntu | bash

Funciona en Ubuntu/Debian, Fedora/RHEL y Arch. En un Mac, usa curl -fsSL https://dist.canebaycomputers.com/zeltro/mac | bash en su lugar, y Windows tiene un .exe de instalación que también configura WSL2 (consulta Windows). La primera vez que se abre, la app muestra un breve formulario de configuración y ejecuta zeltro configure por ti; si ya configuraste Zeltro en una terminal, se salta el formulario.

Los paquetes están en la página de versiones. Consulta Descargas para saber cuál usar.

Actualizar#

zeltro update           # git pull the CLI only — nothing else is touched
zeltro update --full    # also re-run the platform installer and re-pull Docker images

--full detiene los proyectos en ejecución.

Desinstalar#

zeltro uninstall                    # remove Zeltro's Docker containers, volumes and networks
zeltro uninstall --delete-images    # also remove the Docker images

sudo rm -f /usr/local/bin/zeltro
sudo rm -rf /usr/local/share/zeltro-cli
sudo rm -f /usr/share/bash-completion/completions/zeltro /etc/bash_completion.d/zeltro
sudo rm -rf /etc/zeltro-cli         # optional: also remove configuration

Sin --delete-images, zeltro uninstall pregunta si quieres eliminar las imágenes.

Se elimina: los contenedores de los servicios compartidos, los contenedores de los proyectos, y los volúmenes y redes de Zeltro. Los volúmenes contienen las bases de datos compartidas, así que se borra la base de datos de todos los proyectos. Antes, haz un volcado de lo que quieras conservar. El docker-compose.yaml de cada proyecto se renombra a docker-compose.yaml.backup.

Se conserva: todo el código fuente de tus proyectos, los contenedores e imágenes que no son de Zeltro, y el propio Docker.

¿Encontraste un error en esta traducción? Avísanos en GitHub.