`%gall`: Releasing an App

Overview

Teaching: 15 min
Exercises: 30 min

Questions

• How can I deploy a release-worthy %gall app?

• How can I authenticate my app?

Objectives

• Sign and deploy the app.

• Install the app on another ship (planet, moon, or comet).

Installing an App

For a long time Urbit was too unstable to develop on easily, but over the past couple years that’s improved greatly. Now the biggest hurdle to getting more apps on Urbit is that there’s no real way to distribute them.

What makes a regular %gall app into a deployed app? In the past, anyone wanting to use a %gall app has needed to access a repo, copy the files down into app/, and manually start the app. If something was buggy, you risked lobotomizing your ship, so it was common to set up moons to run installed agents on. Not total bedlam, but not for the faint of heart.

Grid and %docket automate most of the process now for users. Software distribution has now become a first-class service on Mars.

References

• ~rovnys-ricfer, “Third-Party Software Distribution in Urbit”
• Tlon Corporation, “Dojo Tools (for Distribution”)

Installing an App

We can install a remote app onto our local ship at the command line (rather than via the browser UI).

> |install ~paldev %pals
>=
ames: czar dev.urbit.org: ip .35.227.173.38
; ~paldev is your neighbor
kiln: activated install into %pals from [~paldev %pals]
kiln: downloading update for %pals from [~paldev %pals]
kiln: finished downloading update for %pals from [~paldev %pals]
kiln: merging into %pals from [~paldev %pals]
kiln: merge into %pals succeeded
kiln: commit detected at %pals from [~paldev %pals]
gall: installing %pals

(Or try |install ~paldev %picture or |install ~dister-dotnet-ritpub-sipsyl %urchatfm for other examples.)

This should automatically start any appropriate agents. Check agent status per desk:

> +agents %pals
status: running   %pals

Resources

• ~palfun-foslup, “pals”

Releasing an App

You have seen how to install and activate an agent on your local ship. Let’s look at how to set up and deploy your own app onto the network.

The basic concept of software distribution for Urbit is that a ship has a desk with self-contained agent code and a %docket mark which

Broadly, speaking, desks look the same, except for some modest additions for agent registration. The directories still obtain as follows:

• /app for agents
• /gen for generators
• /lib for library and helper files
• /mar for marks
• /sur for shared structures
• /ted for threads

These new files contain critical information to instrument the distributed software:

• /sys/kelvin: kernel Kelvin version (required)

  base/sys.kelvin:

    [%zuse 420]
  

• /desk/bill: a list of agents to run automatically (for %kiln) (optional)

  base/desk.bill:

    :~  %acme
        %azimuth-tracker
        %dbug
        %dojo
        %eth-watcher
        %hood
        %herm
        %lens
        %ping
        %spider
    ==
  

• /desk/docket: app metadata (for %docket) (optional)

  base/sur/docket.hoon:

    +$  clause
      $%  [%title title=@t]
          [%info info=@t]
          [%color color=@ux]
          [%glob-http url=cord hash=@uvH]
          [%glob-ames =ship hash=@uvH]
          [%image =url]
          [%site =path]
          [%base base=term]
          [%version =version]
          [%website website=url]
          [%license license=cord]
      ==
  

  Example:

    :~
      title+'Delta'
      info+'A distributed peer-to-peer poke demonstration app.'
      color+0xcd.cdcd
      glob-ames+[~zod 0v0]
      image+'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f5/Greek_uc_delta.svg/1200px-Greek_uc_delta.svg.png'
      base+'delta'
      version+[0 0 1]
      license+'MIT'
      website+'https://en.wikipedia.org/wiki/Delta_Force'
    ==
  

Setup

To set this up, the first thing we need to do is create a new desk in %clay which will hold all of the relevant information about the app, including files and metadata. Typically we base this on our %base desk:

|merge %new-desk ~sampel-palnet %base

Mount and commit the appropriate files. Then make the new desk public:

|public %new-desk

This is a $docket mark with annotation:

+$  href                                :: where a tile links
  $%  [%glob base=term =glob-location]  :: location of client-side data
      [%site =path]                     :: location of server-rendered frontend
  ==                                    ::
::                                      ::
+$  url   cord                          :: URL type
::                                      ::
+$  glob-location                       :: how to retrieve glob (client-side)
  $%  [%http =url]                      :: HTTP source, if applicable
      [%ames =ship]                     :: %ames source, if applicable
  ==                                    ::
::                                      ::
+$  version                             :: version of app (not Kelvin version)
  [major=@ud minor=@ud patch=@ud]       ::
::                                      ::
+$  docket                              ::
  $:  %1                                :: Docket protocol tag
      title=@t                          :: text on home screen
      info=@t                           :: long-form description
      color=@ux                         :: app tile color
      =href                             :: link to client bundle
      image=(unit url)                  :: app tile background
      =version                          :: version of app (not Kelvin version)
      website=url                       :: URL to open on click
      license=cord                      :: software release license
  ==                                    ::

References

• Tlon Corporation, “Distribution”

Key Points

• The Urbit software distribution service affords a straightforward way to deploy, update, and remove %gall apps.