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:
- Como se instala a aplicação?
- Como se atualiza e quem o faz?
- É possível voltar a uma versão anterior?
- Quem a mantém: eu, a comunidade ou um revisor externo?
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:
- Um
.debou.rpmdescarregado do GitHub não se atualiza. O utilizador teria de vigiar sozinho as novas versões. - Para se atualizar, precisas de um repositório apt ou dnf próprio: chave de assinatura, alojamento e manutenção dos metadados. Para um único autor é uma carga desproporcionada.
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:
- Traz as suas próprias dependências (git, curl, ruby), pelo que é mais pesado do que um simples binário. Num contentor pequeno isso pode incomodar.
- Se a fórmula não tiver um arquivo pré-compilado, o Homebrew compilaria a partir do código-fonte no servidor. Por isso é preciso apontar para binários prontos.
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.
- Repositório com o código-fonte. No servidor tem de haver um compilador (no caso do Go, a toolchain) e, depois de cada
git pull, a aplicação tem de ser construída de novo. A atualização deixa assim de ser apenas um download e passa a incluir um build, que pode falhar no servidor. - Repositório só com binários prontos. Considerei isto como atalho. Não é preciso compilar nada, mas o git não foi feito para isso: cada versão do binário fica para sempre no histórico, pelo que o clone, passadas poucas versões, cresce para centenas de megabytes. Clonam-se ainda todas as plataformas, não apenas a tua. E nada verifica que o binário descarregado é aquele que lançaste (sem somas de verificaçã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
| Caminho | Instalação | Atualização | Rollback | Quem mantém |
|---|---|---|---|---|
| Download manual | descarregar e extrair | manual | manual | utilizador |
| Homebrew (macOS, Linux) | brew install | brew upgrade | brew install de uma versão concreta (limitado) | eu (tap) |
| winget | winget install | winget upgrade | versão concreta | eu + revisor |
| Scoop | scoop install | scoop update | scoop reset | eu (bucket) |
| Flatpak | flatpak install | flatpak update | flatpak update --commit | eu + Flathub |
| Docker | docker pull | mudança de tag | mudança de tag | eu (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:
- macOS: Homebrew (cask para GUI, fórmula para CLI), com notarização.
- Windows: winget, eventualmente Scoop para CLI e aplicações portable.
- Linux: Flatpak para GUI, Homebrew para CLI.
- Servidor: Homebrew com
brew services, ou Docker com a tag da versão.
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.