git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/docs/userspace/dist/docket.md
296 lines 7.5 kB history raw
1+++
2title = "Docket File"
3weight = 3
4template = "doc.html"
5+++
7The 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](/docs/userspace/dist/glob), and some additional metadata.
9The docket file is read by the `%docket` agent when a desk is `|install`ed. 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.
11The 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.
13The 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.
15The file must contain a `hoon` list with a series of clauses. The clauses are defined in `/sur/docket.hoon` as:
17```hoon
18+$ clause
19 $% [%title title=@t]
20 [%info info=@t]
21 [%color color=@ux]
22 [%glob-http url=cord hash=@uvH]
23 [%glob-ames =ship hash=@uvH]
24 [%image =url]
25 [%site =path]
26 [%base base=term]
27 [%version =version]
28 [%website website=url]
29 [%license license=cord]
30 ==
31```
33The `%image` clause is optional. It is mandatory to have exactly one of either `%site`, `%glob-http` or `%glob-ames`. All other clauses are mandatory.
35Here's what a typical docket file might look like:
37```hoon
38:~
39 title+'Foo'
40 info+'An app that does a thing.'
41 color+0xf9.8e40
42 glob-ames+[~zod 0v0]
43 image+'https://example.com/tile.svg'
44 base+'foo'
45 version+[0 0 1]
46 license+'MIT'
47 website+'https://example.com'
48==
49```
51Details of each clause and their purpose are described below.
53---
55## `%title`
57_required_
59The `%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.
61#### Type
63```hoon
64[%title title=@t]
65```
67#### Example
69```hoon
70title+'Bitcoin'
71```
73---
75## `%info`
77_required_
79The `%info` field is a brief summary of what the app does. It will be shown as the subtitle in _App Info_.
81#### Type
83```hoon
84[%info info=@t]
85```
87#### Example
89```hoon
90info+'A Bitcoin Wallet that lets you send and receive Bitcoin directly to and from other Urbit users'
91```
93---
95## `%color`
97_required_
99The `%color` field specifies the color of the app tile as an `@ux`-formatted hex value.
101#### Type
103```hoon
104[%color color=@ux]
105```
107#### Example
109```hoon
110color+0xf9.8e40
111```
113---
115## `%glob-http`
117_exactly one of either this, [glob-ames](#glob-ames) or [site](#site) is required_
119The `%glob-http` field specifies the URL and hash of the app's [glob](/docs/userspace/dist/glob) if it is distributed via HTTP.
121#### Type
123```hoon
124[%glob-http url=cord hash=@uvH]
125```
127#### Example
129```hoon
130glob-http+['https://example.com/glob-0v1.s0me.h4sh.glob' 0v1.s0me.h4sh]
131```
133---
135## `%glob-ames`
137_exactly one of either this, [glob-http](#glob-http) or [site](#site) is required_
139The `%glob-ames` field specifies the ship and hash of the app's [glob](/docs/userspace/dist/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](/docs/userspace/dist/glob#globulator).
141#### Type
143```hoon
144[%glob-ames =ship hash=@uvH]
145```
147#### Example
149```hoon
150glob-ames+[~zod 0v0]
151```
153---
155## `%site`
157_exactly one of either this, [glob-ames](#glob-ames) or [glob-http](#glob-http) is required_
159It's possible for an app to handle HTTP requests from the client directly rather than with a separate [glob](/docs/userspace/dist/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.
161For more information on direct HTTP handling with a Gall agent or generator, see the [Eyre Internal API Reference](/docs/arvo/eyre/tasks) documentation.
163#### Type
165```hoon
166[%site =path]
167```
169#### Example
171```hoon
172site+/foo/bar
173```
175---
177## `%image`
179_optional_
181The `%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.
183The given image will be displayed on top of the [color](#color)ed tile. The app [title](#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.
185It 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.
187#### Type
189```hoon
190[%image =url]
191```
193The `url` type is a simple `cord`:
195```hoon
196+$ url cord
197```
199#### Example
201```hoon
202image+'http://example.com/icon.svg'
203```
205---
207## `%base`
209_required_
211The `%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 `path`s of the glob contents themselves should not include this base element.
213#### Type
215```hoon
216[%base base=term]
217```
219#### Example
221```hoon
222base+'bitcoin'
223```
225---
227## `%version`
229_required_
231The `%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.
233#### Type
235```hoon
236[%version =version]
237```
239The `version` type is just a triple of three numbers:
241```hoon
242+$ version
243 [major=@ud minor=@ud patch=@ud]
244```
246#### Example
248```hoon
249version+[0 0 1]
250```
252---
254## `%website`
256_required_
258The `%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.
260#### Type
262```hoon
263[%website website=url]
264```
266The `url` type is a simple `cord`:
268```hoon
269+$ url cord
270```
272#### Example
274```hoon
275website+'https://example.com'
276```
278---
280## `%license`
282_required_
284The `%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.
286#### Type
288```hoon
289[%license license=cord]
290```
292#### Example
294```hoon
295license+'MIT'
296```