Instalação

O Zeltro roda no Linux e no macOS, e no Windows pelo app para desktop, que configura o Zeltro dentro do WSL2 para você (veja Windows abaixo).

Rode todos os instaladores com o seu usuário normal, não como root. Eles pedem sua senha do sudo quando precisam.

Instalação em uma linha#

Estas linhas instalam só o CLI. Para ter também o app para desktop, use as linhas em O app para desktop. Elas instalam o CLI para você se ele estiver faltando.

Plataforma Comando
Ubuntu 22.04 / 24.04 / 26.04 e distros baseadas no 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 link curto redireciona para o install-<os>.sh correspondente no repositório zeltro-cli.

O Debian em si, RHEL, Rocky e Alma ainda não são suportados. O instalador do Ubuntu usa o repositório de pacotes do Docker para Ubuntu, e o instalador do Fedora usa o repositório do Docker para Fedora. Nenhum dos dois tem pacotes para essas distros.

Depois da instalação, no Linux, saia da sessão e entre de novo (veja Todos os Linux). Em seguida, rode uma vez:

zeltro configure

Cada instalador configura o Docker, o Node.js (via nvm, se você ainda não tiver o Node 16 ou mais recente), o Git, o jq, um comando trash, o ImageMagick, o rsvg-convert e o GitHub CLI. Depois clona o Zeltro em /usr/local/share/zeltro-cli e cria o link do comando zeltro em /usr/local/bin. No macOS ele também instala as Xcode Command Line Tools, o Homebrew e o Docker Desktop, se algum deles estiver faltando.

O zeltro configure faz o seguinte:

  • escreve /etc/zeltro-cli/.env
  • escolhe uma sub-rede Docker privada
  • cria o seu diretório de projetos (~/zeltro-projects por padrão)
  • define seu nome e e-mail do Git, se ainda não estiverem definidos
  • instala o autocompletar com Tab do bash
  • inicia os serviços compartilhados

Observações por plataforma#

Todos os Linux#

O instalador adiciona você ao grupo docker. Saia da sessão e entre de novo (ou reinicie) antes de usar o Zeltro, senão as chamadas ao Docker serão negadas. Via SSH, basta reconectar.

macOS#

O instalador coloca o Docker Desktop. Abra-o uma vez e aceite a licença. O Docker Desktop é gratuito para uso pessoal, educação e pequenas empresas, e empresas maiores precisam de uma assinatura paga do Docker (termos do Docker). O Docker Desktop precisa estar rodando sempre que você usar o Zeltro. Ele suporta a versão atual do macOS e as duas anteriores.

O Docker Desktop mantém os contêineres dentro de uma VM, então o IP do contêiner não pode ser acessado a partir do Mac. Em vez disso, o zeltro status mostra um endereço http://localhost:<port> para cada projeto.

Arch#

O pacman -Syu faz uma atualização completa do sistema, que muitas vezes substitui o kernel em execução. Quando isso acontece, o Docker não consegue iniciar até você reiniciar. O instalador detecta isso e mostra uma etapa REBOOT NOW. Reinicie e rode o instalador de novo para terminar.

Fedora: SELinux#

O Fedora roda o SELinux em modo enforcing, e o Zeltro faz bind mount do diretório de cada projeto no seu contêiner.

O Docker CE desativa por padrão o confinamento do SELinux (os contêineres rodam sem confinamento como spc_t), então uma instalação padrão não é afetada. Quando o suporte a SELinux do Docker é ativado ("selinux-enabled": true em /etc/docker/daemon.json), um diretório de projeto sem rótulo faz todo contêiner receber Permission denied.

O zeltro configure rotula o seu diretório de projetos como container_file_t, então o Zeltro funciona nos dois casos. Se você mover o diretório de projetos manualmente, rode zeltro configure de novo para refazer o rótulo.

Windows#

Baixe o app para desktop em zeltro.ai/download/windows (um .exe de instalação em beta; veja Downloads). O Zeltro em si roda no Linux, então no Windows ele roda dentro do WSL2, e o app configura isso para você:

  1. O instalador pede permissão de administrador uma vez. O Windows mostra o aviso de sempre, perguntando se você quer permitir que o app faça alterações. Com essa permissão, o instalador ativa os recursos do Windows de que o WSL2 precisa (WSL e Plataforma de Máquina Virtual) e atualiza o WSL. Se o Windows precisar reiniciar por causa desses recursos, a última página do instalador avisa.
  2. O app faz o resto na primeira abertura, sem mais pedidos de administrador. Ele instala o Ubuntu 24.04 no WSL2 e instala e configura o Zeltro dentro dele. Você não precisa digitar nada em um terminal.

As atualizações do app pulam a etapa de administrador. Se preferir manter seus projetos em outro computador, o app também pode controlar o Zeltro em uma máquina Linux ou em um Mac via SSH (veja Downloads).

Também existe um script de CLI mais antigo, install-windows.ps1, que faz a mesma configuração a partir de um terminal. Ele será aposentado, agora que o app para desktop faz isso. Ele precisa de um PowerShell aberto com Executar como administrador:

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

O script roda em duas etapas, porque ativar os recursos do WSL no Windows exige reiniciar. Ele se agenda para continuar depois que você entrar de novo. Ele precisa do Windows 10 versão 2004 (build 19041) ou mais recente, ou do Windows 11, e recusa builds mais antigas antes de mudar qualquer coisa. Isso corresponde ao mínimo que a Microsoft indica para o wsl --install.

O WSL2 precisa de virtualização por hardware: VT-x/AMD-V ativado na BIOS/UEFI, além de SLAT. Se ela estiver desligada, o app avisa e mostra como ativá-la nas configurações de BIOS/UEFI do seu computador. (Pelo script, o download do Ubuntu dá certo, mas o registro falha com HCS_E_HYPERV_NOT_INSTALLED.) Isso também impede rodá-lo dentro de uma VM do VirtualBox, porque o VirtualBox não repassa o SLAT para o convidado.

Duas coisas se comportam de outro jeito no WSL:

  • O WSL desliga uma distro ociosa e para os contêineres junto com ela. Mantenha um terminal aberto, ou rode wsl -d Ubuntu-24.04 -u root -e sleep infinity.
  • Acesse os projetos pelo endereço LAN ACCESS que o zeltro status mostra. Ele é o endereço da VM do WSL e muda quando o WSL reinicia, então consulte-o no status toda vez em vez de salvá-lo nos favoritos.

Instalar a partir de uma cópia local#

Use isto se você quiser trabalhar no próprio Zeltro. Quando você roda um instalador de dentro de uma cópia local do repositório, ele pula o git clone e cria um link simbólico de /usr/local/share/zeltro-cli para a sua pasta.

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

Configuração#

Pode rodar o zeltro configure de novo sem medo. Ele usa os valores existentes em /etc/zeltro-cli/.env como padrão.

Opção Descrição
--git-name <name> Nome de usuário do Git
--git-email <email> E-mail do usuário do Git
--projects-dir <dir> Diretório de projetos (padrão: o existente, ou ~/zeltro-projects)
--vpc-subnet <A.B.C> Sub-rede da VPC Docker (padrão: a existente, ou uma 10.x.x aleatória)
--non-interactive, -y Nunca pergunta nada; aceita o padrão para tudo o que não for passado como flag

Para uma configuração totalmente automática, como em um script, em CI ou ao preparar uma máquina para um agente:

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

O Zeltro não pede credenciais da AWS nem autenticação no GitHub, e não precisa de nenhuma das duas. Nada no Zeltro usa a AWS. Você só precisa de autenticação no GitHub para as flags opcionais --github e para clone fork e clone new-repo. Se você usá-las sem autenticação, elas pedem para você rodar gh auth login nesse momento.

O Zeltro escolhe a sub-rede da VPC Docker para você. É uma /24 privada na faixa 10.x.x, nunca 10.0.x, para não colidir com a rede 10.0.0.0/24 que muitas redes domésticas e de escritório usam. Use --vpc-subnet se precisar de uma faixa específica.

O autocompletar com Tab cobre comandos, nomes de projetos, nomes de frameworks e nomes 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  ...

O app para desktop#

O app para desktop do Zeltro é opcional. No Linux, um comando o instala, e instala este CLI antes se o zeltro estiver faltando:

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

Funciona no Ubuntu/Debian, no Fedora/RHEL e no Arch. No Mac, use curl -fsSL https://dist.canebaycomputers.com/zeltro/mac | bash, e o Windows tem um .exe de instalação que também configura o WSL2 (veja Windows). Na primeira abertura, o app mostra um pequeno formulário de configuração e roda o zeltro configure para você; se você já configurou o Zeltro em um terminal, ele pula o formulário.

Os pacotes estão na página de releases. Veja em Downloads qual usar.

Atualização#

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

O --full para os projetos em execução.

Desinstalação#

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

Sem --delete-images, o zeltro uninstall pergunta se deve remover as imagens.

Removido: os contêineres dos serviços compartilhados, os contêineres dos projetos e os volumes e redes do Zeltro. Os volumes guardam os bancos de dados compartilhados, então o banco de dados de todos os projetos é apagado. Faça antes um dump de tudo o que quiser manter. O docker-compose.yaml de cada projeto é renomeado para docker-compose.yaml.backup.

Mantido: todo o código-fonte dos seus projetos, contêineres e imagens que não são do Zeltro, e o próprio Docker.

Achou um erro nesta tradução? Avise a gente no GitHub.