Installers and download links

How the installer works, download links, and building a download for your application

Chapter 15 of 34Current for Gritpack 1.2.63Source: docs/guide/15-installers-and-download-links.md

The people who use your application should not have to learn Gritpack first. They should click a download, confirm once, and find the program ready, and afterwards it should stay up to date. Gritpack's installer does exactly that: it installs one application, and installs Gritpack too when it is missing, so that gritpack app upgrade keeps both current. This chapter explains what the installer does, the links the public hub serves for it, and how you build a download for your own application.

What you will be able to do

  • explain to a user what happens when they run an installer;
  • give people a one-line install or a download link for an application on the public hub;
  • run the installer unattended, without touching PATH;
  • build an install script or a Mac download for your application with gritpack installer build;
  • understand invitation links that join someone to a private hub.

What the installer does

The installer is one small program per platform, released with every Gritpack version. You never need to build it. Whichever way it reaches the person (a download, a one-line command), it does the same things in the same order:

  1. Works out which application. From its command line, or from its own file name, or from a small label file beside it.
  2. Asks once, showing the application's name, version, description and the hub it comes from. --yes answers for unattended use. With no terminal to ask in and no --yes, it stops rather than guess.
  3. Installs Gritpack from get.gritpack.org if no gritpack command is installed yet, so the application can be kept up to date.
  4. Installs the application, exactly as gritpack install would, into the person's Gritpack home, with the same checks and the same receipt.
  5. Offers to put ~/.frogfish/gritpack/bin on PATH, once, by adding a line to the login profile of the person's shell (~/.zprofile, ~/.bash_profile or ~/.profile), or to the user's Path on Windows. --no-modify-path declines.
  6. Says how to run it.

Here is a real run in a terminal, installing a small public application on a machine with no Gritpack:

$ installer @frogfish/scroll-throttle --yes --no-modify-path
Install scroll-throttle 1.0.0 from get.gritpack.org?
  Rate-limits X11 scroll-wheel events; fixes unusably fast scrolling caused by a high-resolution trackpad relayed through RDP to a Linux X11 session
Installing Gritpack 1.2.63, which keeps scroll-throttle up to date … ok
Downloading @frogfish/scroll-throttle 1.0.0 … verified
Installing scroll-throttle … ok
Add ~/.frogfish/gritpack/bin to PATH to run the commands by name
scroll-throttle is ready: run `scroll-throttle`

Without --no-modify-path it would have offered to add that directory to PATH instead of printing the reminder. Running the installer again later upgrades the application to its newest version.

The installer's options, from installer --help:

OptionWhat it does
[PACKAGE]The application to install; read from the label or the installer's own file name when omitted
--hub <HUB>The hub to install from; default the label's, else get.gritpack.org
-y, --yesAnswer yes to every question, for unattended installation
--home <HOME>The Gritpack home to install into; default ~/.frogfish/gritpack
--no-modify-pathDo not add the command directory to PATH
--ca <CA>A certificate authority for a hub whose certificate the system does not trust
--guiOpen the window even from a terminal (builds with the window only)
--code <CODE>A download code from an invitation page

The installer never runs code from the package while installing, and it writes nothing outside the person's Gritpack home and, if they agree, one line in their shell profile.

Careful. The installer installs public applications. It does not log in, so it cannot install from a private hub that needs a login: the person runs gritpack login first, then gritpack install. Invitation links, at the end of this chapter, are the way to bring someone onto a private hub.

Installing Gritpack itself

Install Gritpack covers this from the user's side. The pieces, for reference:

PlatformHow
Mac, Windows, LinuxDownload from https://gritpack.org/install/, or directly from https://gritpack.org/download/mac, /download/windows or /download/linux
Linux or a Mac terminalcurl -fsSL https://get.gritpack.org/install/gritpack \| sh
Windows PowerShellirm https://get.gritpack.org/install.ps1/gritpack \| iex

The Mac and Windows downloads are not yet signed with a Developer ID or a Windows code-signing certificate, so the operating system warns the first time; the install page says how to proceed.

One-line installs for any public application

The public hub serves an install script for every application it holds. Put the package name at the end of the address:

curl -fsSL https://get.gritpack.org/install/@frogfish/scroll-throttle | sh

The script is short and worth reading before you pipe it into a shell:

curl -fsSL https://get.gritpack.org/install/gritpack | less

It works out the platform, downloads the installer for that platform from the hub, checks it against a SHA-256 checksum written into the script itself, and runs it, naming the package and the hub. If the checksum does not match, nothing is installed. Arguments after sh -s -- reach the installer:

curl -fsSL https://get.gritpack.org/install/@frogfish/scroll-throttle | sh -s -- --yes

On Windows, the PowerShell form is the same idea:

irm https://get.gritpack.org/install.ps1/@frogfish/scroll-throttle | iex

irm and iex cannot pass arguments, so for --yes use the longer form the script's own first lines suggest:

& ([scriptblock]::Create((irm https://get.gritpack.org/install.ps1/@frogfish/scroll-throttle))) --yes

The install scripts cover Linux on x86-64, Macs with Apple silicon, and Windows on x86-64. On other platforms the script says there is no installer for that platform yet.

Downloads named for their package

People who do not use a terminal want a file to double-click. The public hub serves the same installer under a name that says what it installs:

https://get.gritpack.org/installer/<platform>/<package>

<platform> is x86_64-unknown-linux-gnu, aarch64-apple-darwin or x86_64-pc-windows-msvc. The file arrives with a name built from the package, with _ standing for the / of a scope:

PackageLinuxWindowsMac
gritpackgritpack.installergritpack.installer.exegritpack.installer.app, in a zip
@frogfish/scroll-throttlefrogfish_scroll-throttle.installerfrogfish_scroll-throttle.installer.exefrogfish_scroll-throttle.installer.app, in a zip

The installer reads its own file name to know what to install. Copy marks that browsers add, such as (1), are ignored. A renamed file installs whatever its new name says, after showing the package and asking. Because the name carries no hub, these downloads always install from get.gritpack.org.

That is why the name of an application package cannot contain _: it would be ambiguous in a download name, so the hub refuses it.

On Windows, a double-clicked installer opens a small window and asks there. A console window shows for a moment first, because the same program also works in a terminal.

Build a download for your application

gritpack installer build turns a published application into a download you can host yourself. It needs the application to be on a hub that also serves the installer, which today means the public hub.

For Linux and Mac terminals, it saves the install script:

$ gritpack installer build @frogfish/scroll-throttle --platform linux --from get.gritpack.org
wrote install-scroll-throttle.sh for @frogfish/scroll-throttle
the hub serves the same script: curl -fsSL https://get.gritpack.org/install/@frogfish/scroll-throttle | sh

The script is the one the hub serves, pinned to the newest installer and its checksum, so you can put it on your own website. It does not need rebuilding when you release a new version of your application, because the installer always installs the newest version for the platform. Rebuild it when you want it to use a newer installer.

For Macs, --platform macos builds an application bundle called Install <Title> that carries the installer and a label naming your package. On a Mac it is a .dmg; on other systems a .zip:

$ gritpack installer build @frogfish/scroll-throttle --platform macos --title "Scroll Throttle" --from get.gritpack.org
wrote Install Scroll Throttle.zip for @frogfish/scroll-throttle (installer 1.2.63, aarch64-apple-darwin; not notarized)

"Not notarized" is honest: the bundle is not signed with an Apple Developer ID, so macOS warns the first time it is opened.

--title sets the name people see (default: the package's own name), and --output sets where the file goes (default: install-<name>.sh, or Install <Title>.dmg or .zip).

For automation. installer build takes the usual hub options, so a release job can build downloads right after gritpack publish. Use --from to name the hub explicitly in CI.

If the hub you name does not serve installers, the command fails with a "not found" error (exit code 5) rather than writing an incomplete download.

Invitation links

To bring someone onto a private hub, its administrator sends an invitation (Administering a hub). Usually that is an email address and a one-time code that the person passes to gritpack login. An administrator can instead make the invitation a link:

$ gritpack admin user invite bea@example.com --download --enrollment-hub packages.example.com:7445 --package-hub packages.example.com:443
invitation=01a1e868-b459-7c22-b169-9bf9487961f5 account=01a1e868-b3e8-7870-82c6-fc0f4e3af433 expires_at=1794986938 link=https://get.gritpack.org/i/J11F3QAC2N

What the invited person sees:

  1. They open the link. The page offers a Mac download, and for Linux and Mac terminals a one-line command of the form curl -fsSL https://get.gritpack.org/install/gritpack | sh -s -- --code <code>.
  2. The Mac download is called Join <Profile> - <code>.app, in a zip. The ten characters at the end of its name are the code; the program reads its own name, as the named installers do.
  3. Opening it asks "Join <hub> as <email>?". On confirmation it installs Gritpack if needed and logs in to the private hub, saving a login profile. If Gritpack is already installed, it downloads nothing and only logs in.

The code works once, only together with the invited email address, and stops working when the invitation expires or is revoked. An unknown, used, revoked or expired code all look the same from outside: "not found".

Today an invitation logs the person in; installing a private application in the same step is Planned. After joining, they run gritpack install <application> themselves, or use gritpack app upgrade to keep it current.

What just happened

  • The installer installs one application, and Gritpack if it is missing, after one confirmation, with the same checks as gritpack install.
  • get.gritpack.org/install/<package> and install.ps1/<package> serve checksummed one-line installs for any public application.
  • get.gritpack.org/installer/<platform>/<package> serves a double-clickable installer named for its package.
  • gritpack installer build saves the install script or builds a Mac bundle you can host yourself.
  • Invitation links bring a person onto a private hub with one download.

You can stop here

If you ship a public application and want people to get it in one step, you have what you need.

Next