The docket file sets various options for desks with a tile and (usually) a browser-based front-end of some kind. Mainly it configures the appearance of an app's tile, the source of its glob, and some additional metadata.
The docket file is read by the %docket agent when a desk is |installed. The %docket agent will fetch the glob if applicable and create the tile as specified on the homescreen. If the desk is published with :treaty|publish, the information specified in the docket file will also be displayed for others who are browsing apps to install on your ship.
The docket file is optional in the general case. If it is omitted, however, the app cannot have a tile in the homescreen, nor can it be published with the %treaty agent, so others will not be able to browse for it from their homescreens.
The docket file must be named desk.docket-0. The %docket mark is versioned to facilitate changes down the line, so the -0 suffix may be incremented in the future.
The file must contain a hoon list with a series of clauses. The clauses are defined in /sur/docket.hoon as:
+$ 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]==
The %image clause is optional. It is mandatory to have exactly one of either %site, %glob-http or %glob-ames. All other clauses are mandatory.
Here's what a typical docket file might look like:
:~title+'Foo'info+'An app that does a thing.'color+0xf9.8e40glob-ames+[~zod 0v0]image+'https://example.com/tile.svg'base+'foo'version+[0 0 1]license+'MIT'website+'https://example.com'==
Details of each clause and their purpose are described below.
%title
required
The %title field specifies the name of the app. The title will be the name shown on the app's tile, as well as the name of the app when others search for it.
Type
[%title title=@t]
Example
title+'Bitcoin'
%info
required
The %info field is a brief summary of what the app does. It will be shown as the subtitle in App Info.
Type
[%info info=@t]
Example
info+'A Bitcoin Wallet that lets you send and receive Bitcoin directly to and from other Urbit users'
%color
required
The %color field specifies the color of the app tile as an @ux-formatted hex value.
Type
[%color color=@ux]
Example
color+0xf9.8e40
%glob-http
exactly one of either this, glob-ames or site is required
The %glob-http field specifies the URL and hash of the app's glob if it is distributed via HTTP.
Type
[%glob-http url=cord hash=@uvH]
Example
glob-http+['https://example.com/glob-0v1.s0me.h4sh.glob' 0v1.s0me.h4sh]
%glob-ames
exactly one of either this, glob-http or site is required
The %glob-ames field specifies the ship and hash of the app's glob if it is distributed from a ship over Ames. If the glob will be distributed from our ship, the hash can initially be 0v0 as it will be overwritten with the hash produced by the Globulator.
Type
[%glob-ames =ship hash=@uvH]
Example
glob-ames+[~zod 0v0]
%site
exactly one of either this, glob-ames or glob-http is required
It's possible for an app to handle HTTP requests from the client directly rather than with a separate glob. In that case, the %site field specifies the path of the Eyre endpoint the app will bind. If %site is used, clicking the app's tile will simply open a new tab with a GET request to the specified Eyre endpoint.
For more information on direct HTTP handling with a Gall agent or generator, see the Eyre Internal API Reference documentation.
Type
[%site =path]
Example
site+/foo/bar
%image
optional
The %image field specifies the URL of an image to be displayed on the app's tile. This field is optional and may be omitted entirely.
The given image will be displayed on top of the colored tile. The app title (and hamburger menu upon hover) will be displayed on top of the given image, in small rounded boxes with the same background color as the main tile. The given image will be displayed at 100% of the width of the tile. The image's corners will be hidden by the rounded corners of the tile, so the image itself needn't have rounded corners. The tile is a perfect square, so if the image should occupy the whole tile, it should also be a perfect square. If the image should be a smaller icon in the center of the tile (like the bitcoin tile), it should just have a square of transparent negative space around it.
It may be tempting to set the image URL as a root-relative path like /apps/myapp/img/tile.svg and bundle it in the glob. While this would work locally, it means the image would fail to load for those browsing apps to install. Therefore, the image should be hosted somewhere globally available.
Type
[%image =url]
The url type is a simple cord:
+$ url cord
Example
image+'http://example.com/icon.svg'
%base
required
The %base field specifies the base of the URL path of the glob resources. In the browser, the path will begin with /apps, then the specified base, then the rest of the path to the particular glob resource like http://localhost:8080/apps/my-base/index.html. Note the paths of the glob contents themselves should not include this base element.
Type
[%base base=term]
Example
base+'bitcoin'
%version
required
The %version field specifies the current version of the app. It's a triple of three @ud numbers representing the major version, minor version and patch version. In the client, [1 2 3] will be rendered as 1.2.3. You would typically increase the appropriate number each time you published a change to the app.
Type
[%version =version]
The version type is just a triple of three numbers:
+$ version[major=@ud minor=@ud patch=@ud]
Example
version+[0 0 1]
%website
required
The %website field is for a link to a relevant website. This might be a link to the app's github repo, company website, or whatever is appropriate. This field will be displayed when people are browsing apps to install.
Type
[%website website=url]
The url type is a simple cord:
+$ url cord
Example
website+'https://example.com'
%license
required
The %license field specifies the license for the app in question. It would typically be a short name like MIT, GPLv2, or what have you. The field just takes a cord so any license can be specified.
Type
[%license license=cord]
Example
license+'MIT'