Um release, cinco gestores de pacotes: como facilitar aos utilizadores a instalação e a atualização

Instalar é fácil, o que realmente decide é a atualização. Como entregar uma aplicação a partir de uma única tag através de Homebrew, winget, Scoop, Flatpak e Docker.

Lançar uma nova versão de uma aplicação é fácil. Surge um release no GitHub, anexam-se os arquivos e está feito. Só que o utilizador que descarregou a aplicação há meio ano não sabe que existe uma versão nova. E a culpa de não chegar a ela não é dele, mas da forma como lhe entregámos a aplicação.

A instalação é algo pontual. A diferença real entre «descarrega isto do site» e software distribuído como deve ser está na atualização: quem a lança, com que facilidade e se é possível voltar atrás. Resolvi isto para as minhas ferramentas (OmniDB, PgArachne, pg_procrustes, pg_dbml e outras) e cheguei a uma divisão que não tem uma única resposta para todas as plataformas.

Como escolho

Para cada plataforma fiz quatro perguntas:

macOS: Homebrew

No macOS, o Homebrew faz sentido para tudo. A fórmula (formula) serve para a linha de comandos, o cask para aplicações com interface gráfica.

brew install --cask heptau/tap/omnidb   # GUI (cask)
brew install heptau/tap/pg-procrustes   # CLI (fórmula)
brew install heptau/tap/pg-dbml         # CLI (fórmula)
brew upgrade                            # atualização de tudo

A decisão que vale a pena ponderar é tap próprio versus repositório oficial. O tap próprio (heptau/tap) funciona de imediato: basta um repositório no GitHub e alguns ficheiros lá dentro. Para entrar no homebrew-cask oficial é preciso que o projeto já seja suficientemente conhecido e, sobretudo, uma aplicação assinada e notarizada pela Apple (ou seja, uma conta paga de Apple Developer).

O Homebrew, aliás, não contorna o Gatekeeper. Marca a aplicação descarregada com quarentena, tal como o navegador, pelo que o macOS a verifica no primeiro arranque. Existia antes o parâmetro --no-quarantine, com o qual o utilizador desligava a quarentena, mas desde o Homebrew 5.0.0 está obsoleto, porque o Homebrew não quer facilitar o contorno das funcionalidades de segurança do macOS. Os casks sem assinatura estão marcados como obsoletos e o repositório oficial deveria ter removido, desde setembro de 2026, todos os que o Gatekeeper não deixa passar (confirmei-o no anúncio do Homebrew 5.0.0, não na prática).

Daqui resulta uma coisa simples para ti: a assinatura e a notarização são trabalho teu, não do Homebrew. Sem elas, o Gatekeeper bloqueia a aplicação ao utilizador no primeiro arranque, independentemente de como a instalou, e não entras no repositório oficial. Num tap próprio ninguém retira o cask, mas o Gatekeeper no computador do utilizador aplica-se da mesma forma.

Uma coisa útil para os utilizadores, qualquer que tenha sido a forma de instalação: se já tens a aplicação instalada manualmente (descarregando o .dmg ou um zip) e queres geri-la a partir de agora com o Homebrew, não precisas de a apagar e descarregar de novo. Basta:

brew install --cask --adopt heptau/tap/omnidb

O parâmetro --adopt assume a aplicação existente em /Applications, se for idêntica à que o cask instalaria, e a partir daí o Homebrew passa a geri-la, pelo que o brew upgrade a atualiza. Segundo a documentação, os ficheiros existentes têm de ser idênticos aos instalados, por isso serve sobretudo quando tens a mesma versão que o cask. Não pode ser combinado com --force. Para o autor é uma boa notícia: os utilizadores que descarregaram a aplicação do site podem passar para o Homebrew sem reinstalar.

Windows: winget e Scoop

O winget é um gestor de pacotes que faz parte do Windows 11 e do Windows 10 (desde a versão 1809, como parte do componente App Installer). O utilizador escreve winget install e winget upgrade e não precisa de mais nada. Para ti, significa enviar um manifesto como pull request para o repositório microsoft/winget-pkgs. As condições são um URL estável do instalador e instalação silenciosa. A aprovação é mais lenta do que num tap próprio, mas depois do primeiro pacote as versões seguintes podem ser enviadas automaticamente.

Tenho um exemplo com a aplicação gráfica OmniDB. O utilizador escreve:

winget install heptau.OmniDB
winget upgrade heptau.OmniDB

Para uma aplicação gráfica, o mais natural é um instalador a sério (.exe ou .msi), porque tem de criar atalhos, registar a desinstalação e assim por diante. Por isso, o OmniDB constrói um instalador NSIS no momento do release e um script gera o manifesto a partir dele e das somas de verificação. O manifesto é composto por três ficheiros YAML (versão, instalador e descrição). O mais importante é o ficheiro do instalador:

PackageIdentifier: heptau.OmniDB
PackageVersion: 5.5.0
InstallerType: nullsoft
Scope: machine
InstallModes:
  - interactive
  - silent
  - silentWithProgress
UpgradeBehavior: install
Installers:
  - Architecture: x64
    InstallerUrl: https://github.com/heptau/omnidb/releases/download/v5.5.0/OmniDB-win-x64-setup.exe
    InstallerSha256: …
ManifestType: installer

Esse silent é a tal «instalação silenciosa», sem a qual o winget upgrade não poderia correr sem intervenção do utilizador. O identificador heptau.OmniDB tem a forma Publicador.Nome, que é a convenção do winget.

O winget tem uma característica que não encontrei noutros gestores de pacotes: consegue atualizar também uma aplicação que o utilizador instalou manualmente, descarregando o instalador do site. Funciona porque todo o instalador clássico do Windows grava no registo uma entrada para a lista «Aplicações e funcionalidades» (ARP, Add/Remove Programs): nome, publicador e versão. O winget lê essas entradas e tenta emparelhá-las com os pacotes do repositório. Quando consegue, o winget list mostra a aplicação instalada manualmente ao lado das outras e o winget upgrade consegue atualizá-la como se desde o início a tivesse instalado ele.

Daqui sai um conselho prático para o autor: garante que o nome e o publicador no instalador correspondem ao manifesto ou, em alternativa, enumera-os no manifesto no campo AppsAndFeaturesEntries. O emparelhamento apoia-se, afinal, em nomes e versões, e quando falha a aplicação não aparece no winget upgrade ou tem a versão «Unknown». Não se deve portanto encará-lo como garantia, mas como um bónus que é preciso vigiar. O Homebrew tem algo semelhante, mas diferente: não encontra a aplicação por si, o utilizador tem de a «adotar» manualmente (ver o comando --adopt na secção sobre o macOS).

O próprio release acaba depois automaticamente: o script cria um ramo no fork heptau/winget-pkgs e abre um pull request com a nova versão. O primeiro pacote teve de ser enviado manualmente para o winget-pkgs, porque um pacote novo passa por uma aprovação diferente da de um aumento de versão. O script sabe-o e recusa-se a enviar automaticamente um pacote que ainda não exista no upstream.

Para ferramentas de linha de comandos não precisas de instalador. O winget conhece o tipo portable (um .exe autónomo) e, desde a versão 1.4, também zip, de onde extrai o ficheiro portable aninhado. Basta, portanto, o arquivo que já lanças de qualquer forma, e no manifesto muda apenas o tipo. Assim ficaria para o arquivo que o pg_procrustes já publica (ainda não o enviei para o winget-pkgs, é um exemplo):

InstallerType: zip
NestedInstallerType: portable
NestedInstallerFiles:
  - RelativeFilePath: pg_procrustes.exe
Installers:
  - Architecture: x64
    InstallerUrl: https://github.com/heptau/pg_procrustes/releases/download/v0.6.1/pg_procrustes-0.6.1-windows-amd64.zip
    InstallerSha256: 6d361058befc5176516b52017428abd271d41a2b2d5192968b73097de3b549bc

O winget extrai essa ferramenta para o diretório do utilizador e disponibiliza-a no PATH, sem direitos de administrador e sem instalador. Este caminho só o experimentei ao nível da documentação, não num pull request real para o winget-pkgs, por isso confirma os nomes exatos dos campos no esquema do manifesto antes de enviares.

O Scoop é uma boa alternativa para a linha de comandos e para aplicações portable. Instala-se sem direitos de administrador no diretório do utilizador e criar um bucket próprio (o equivalente a um tap) leva uns minutos.

scoop bucket add heptau https://github.com/heptau/scoop-bucket
scoop install pgarachne
scoop update pgarachne

Vale também a pena mencionar o Chocolatey: é um gestor de pacotes mais antigo, usado sobretudo em ambiente empresarial. Para projetos novos, porém, o winget e o Scoop são mais confortáveis.

Linux

Aqui os caminhos para GUI e CLI são diferentes.

Aplicações gráficas: Flatpak

Para aplicações com janela, o Flatpak é uma escolha razoável. A aplicação instala-se a partir do Flathub, atualiza-se com flatpak update e corre numa sandbox. A sandbox é importante precisamente para um cliente PostgreSQL. A aplicação, por si, não vê o ~/.pgpass nem os sockets Unix, pelo que é preciso enumerar expressamente as permissões no manifesto (falo disto com mais pormenor no artigo Aplicações em sandbox: quando o isolamento corta a base de dados do .pgpass).

Do Snap e do AppImage falo só numa frase: o Snap está ligado à Canonical e o AppImage não tem, por si, nenhum mecanismo de atualização.

Linha de comandos: Homebrew

Neste ponto estive inicialmente a pensar em pacotes .deb e .rpm. Esbarrei em duas coisas:

Por isso, a escolha pragmática para mim no Linux é o Homebrew. É o mesmo comando que no macOS, instala-se em /home/linuxbrew/.linuxbrew, não precisa de root e não colide com o gestor de pacotes do sistema. E a fórmula pode ser exatamente a mesma. A minha fórmula do PgArachne tem apenas blocos on_macos e on_linux com ligações para os arquivos pré-compilados do release do GitHub:

on_linux do
  if Hardware::CPU.arm?
    url "https://github.com/heptau/pgarachne/releases/download/v#{version}/pgarachne-linux-arm64.tar.gz"
    sha256 "…"
  else
    url "https://github.com/heptau/pgarachne/releases/download/v#{version}/pgarachne-linux-amd64.tar.gz"
    sha256 "…"
  end
end

Sem compilação, só o download de um binário pronto e a sua verificação contra a soma de verificação.

O Homebrew no Linux tem, porém, também desvantagens, que é justo mencionar:

Servidor: o exemplo do PgArachne

O servidor atualiza-se de forma diferente do desktop. A atualização da gateway à qual as aplicações se ligam deve ser controlada, não silenciosa. Não quero que numa sexta-feira à noite mude sozinha para a nova versão.

O Homebrew permite-o bem:

brew install heptau/tap/pgarachne
brew services start pgarachne      # cria o serviço
brew upgrade pgarachne             # nova versão
brew services restart pgarachne    # reinício após a atualização

No Linux, o brew services cria um serviço systemd de utilizador. Para que corra também sem o utilizador com sessão iniciada, é preciso ativar uma vez o loginctl enable-linger. Se quiseres automatizar as atualizações, basta chamar o brew upgrade a partir do cron ou de um timer do systemd, mas de forma consciente e num momento que tu escolhas.

E o git pull?

Passou-me também pela cabeça a solução mais simples: ter no servidor um clone do repositório e atualizá-lo com git pull. Existem duas variantes e ambas têm um senão.

O curioso é que o Homebrew faz, no fundo, também isto: o tap é um repositório git e o brew update é, no essencial, um git pull. A diferença é que no repositório há apenas pequenas descrições em texto (as fórmulas), não binários. Os binários propriamente ditos descarregam-se dos releases, verificam-se com a soma de verificação e a versão escolhe-se consoante a plataforma. É, portanto, um git pull para os metadados e um download para os dados, e é essa separação que o torna uma solução utilizável.

Para desenvolvimento, o git pull chega. Para produção, usá-lo-ia apenas através de um tap, não diretamente.

Docker: o caminho mais curto para o servidor

Em aplicações de servidor, a atualização menos dolorosa é muitas vezes a de uma imagem Docker com a tag da versão:

services:
  app:
    image: ghcr.io/a-sua-conta/a-sua-app:2.0.2

A atualização é mudar o número da versão e docker compose pull && docker compose up -d. O rollback é o mesmo com o número anterior. É o caminho mais direto para gerir versões, mas pressupõe que já tens Docker no servidor e que o usas.

Confesso que, para já, não publico a imagem do PgArachne. É mais um canal que o GoReleaser saberia servir a partir da mesma tag e, se o acrescentar, será apenas mais um bloco na configuração.

E as aplicações web (PWA)?

Com as PWA a situação é a oposta de tudo o que ficou acima: não precisam de ser atualizadas, porque a atualização acontece no carregamento seguinte da página. Um gestor de pacotes não melhora aqui nada. Resta apenas a instalação, e mesmo essa faz-se no navegador com dois cliques.

Mesmo assim, ocorreu-me se não seria possível instalar o ícone da aplicação através do Homebrew, para que a pessoa a tivesse ao lado das outras aplicações e num Brewfile. No macOS, isso é surpreendentemente simples. Quando se adiciona uma PWA ao ambiente de trabalho no Safari, surge uma .app que contém apenas o Info.plist (com todo o manifesto da aplicação web), o ícone e a assinatura. Nenhum código executável, esse é fornecido pelo sistema. Basta comprimir essa aplicação num zip e expô-la como cask. Para já é só uma demonstração (não publico ainda um release do Lumifex com este ficheiro, pelo que o endereço e a soma são provisórios):

cask "lumifex" do
  version "1.0"
  sha256 "…"

  url "https://github.com/heptau/lumifex/releases/download/v#{version}/Lumifex.app.zip"
  name "Lumifex"
  homepage "https://lumifex.80.cz/"

  depends_on macos: ">= :sonoma"

  app "Lumifex.app"
end

Experimentei que uma cópia com a flag de quarentena (como depois de um download da internet) arranca sem um único erro, apesar de estar assinada apenas ad hoc. Testei-o, porém, apenas no mesmo Mac onde o bundle foi criado, pelo que é uma verificação com reservas.

É preciso admitir o que se ganha com isto e o que não. As atualizações continuam a acontecer dentro da PWA e o brew upgrade não lhes muda nada. Ganha-se um comando de instalação uniforme, um ícone no Launchpad e a possibilidade de ter a aplicação num Brewfile. No Windows e no Linux não esperaria nada tão simples. Um atalho que lance o navegador em modo de aplicação poderia ser criado através do Scoop ou de um pequeno instalador, mas ainda não o experimentei, e no Linux o Flatpak seria um invólucro com um núcleo próprio, não uma ligação.

Comparação

CaminhoInstalaçãoAtualizaçãoRollbackQuem mantém
Download manualdescarregar e extrairmanualmanualutilizador
Homebrew (macOS, Linux)brew installbrew upgradebrew install de uma versão concreta (limitado)eu (tap)
wingetwinget installwinget upgradeversão concretaeu + revisor
Scoopscoop installscoop updatescoop reseteu (bucket)
Flatpakflatpak installflatpak updateflatpak update --commiteu + Flathub
Dockerdocker pullmudança de tagmudança de tageu (registry)

Como fazê-lo sem que seja trabalho extra

Cinco canais soa a cinco tarefas a cada release. A solução é a automação: a partir de uma única tag, todos os artefactos devem gerar-se sozinhos. Para isso uso o GoReleaser, que, a partir de um só código-fonte, constrói binários para todas as plataformas, empacota-os em arquivos e calcula as somas de verificação.

A base da configuração do PgArachne é assim:

version: 2

project_name: pgarachne

builds:
  - id: cli
    main: ./cmd/pgarachne
    binary: pgarachne
    env:
      - CGO_ENABLED=0
    goos: [darwin, linux, windows]
    goarch: [amd64, arm64]
    ldflags:
      - -s -w
      - -X github.com/heptau/pgarachne/internal/version.Version={{ .Version }}

archives:
  - id: cli-archive
    ids: [cli]
    name_template: "{{ .ProjectName }}-{{ .Os }}-{{ .Arch }}"
    formats: [tar.gz]
    format_overrides:
      - goos: darwin
        formats: [zip]
      - goos: windows
        formats: [zip]

checksum:
  name_template: checksums.txt

Esta é a configuração real. A fórmula para o tap é depois gerada pelo meu script a partir das somas de verificação que o GoReleaser produz. O GoReleaser sabe, no entanto, fazer mais e pode criar por si a fórmula, o manifesto para o Scoop e o manifesto para o winget, e enviá-los para o respetivo repositório:

brews:
  - repository:
      owner: heptau
      name: homebrew-tap
    homepage: "https://www.pgarachne.com/"
    description: "PostgreSQL JSON-RPC gateway"

scoops:
  - repository:
      owner: heptau
      name: scoop-bucket
    homepage: "https://www.pgarachne.com/"
    description: "PostgreSQL JSON-RPC gateway"

(Esta segunda parte apresento-a como demonstração das possibilidades, no PgArachne ainda não a uso.)

O que não se consegue automatizar, ou só com dificuldade: a notarização da Apple, a aprovação no Flathub e o pull request para o winget-pkgs, onde no fim há sempre uma pessoa ou um bot a verificar o pacote.

Conclusão

A minha recomendação, que uso neste momento:

O núcleo comum é um só: a atualização é uma funcionalidade do produto, não um acessório. O utilizador deve recebê-la tão facilmente como a instalação e tu deves tê-la a partir de uma única tag, sem cliques manuais.