Site JSON

/docs/gears/developer/reference/site-json/

Overview

A Site JSON file describes the structure of a Site, aka virtual host. Generally, a Site:

  • has a certain hostname, such as family.example.com, or * if the Site should respond to all requests regardless of HTTP host header;
  • has a single administrator, for which username, e-mail address etc. are given;
  • may or may not have SSL/TLS information (key, certificate etc.) so the Site can be served over HTTPS;
  • runs one or more Apps at different context paths, such as Wordpress at /blog, and a wiki at /wiki,
  • each of those Apps may be configured with any number of Accessories (for example, Wordpress plugins or themes), and
  • may also define certain well-known files, such as robots.txt.

UBOS captures all of this information in a single JSON file with a particular structure, called the Site JSON file. You can usually interact with Site JSON files as opaque blobs, but if you like to see the Site JSON file for a Site you have currently deployed, use the ubos-admin showsite command either with the Site’s hostname or SiteId:

% sudo ubos-admin showsite --json --hostname <hostname>

or

% sudo ubos-admin showsite --json --siteid <siteid>

If you run this command as a user other than root, no credential information will be included.

The easiest way of creating a Site JSON file is with the createsite command:

% sudo ubos-admin createsite -n -o newsite.json

(The -n flag will only generate the Site JSON and not deploy the Site; the -o newsite.json flag will save the generated Site JSON to file newsite.json.)

Structure

The Site JSON is a JSON hash with the following entries:

admin (required)
The admin section defines the administrator for the Site. It has the following entries:

userid (required) User identifier for the administrator. Example: admin.

username (required) Human-readable name for the administrator. Example: John Smith.

credential (required) Credential for the administrator account. Example: s3cr3t. Only shown to the root user.

email (required) Contact e-mail for the administrator. Example: admin@family.example.org.

appconfigs (optional)
A JSON array of the AppConfigurations at this Site. There is no significance to the order of the elements in the array. An AppConfiguration is the deployment of an App at a particular Context Path at a particular Site, together with any Accessories and/or Customization Points that are specific to this deployment of the App.
hostname (required)
The hostname for the Site, or *. E.g. family.example.org.
lastupdated (optional)
timestamp for when this Site JSON file was last deployed to the current Device. This data element gets inserted or updated by UBOS in the Site JSON held on the Device every time a Site is deployed.
siteid (required)
The SiteId: a unique identifier for the Site. This is generally an s followed by 40 hex characters. E.g. s054257e710d12d7d06957d8c91ab2dc1b22d7b4c.
tls (optional)
This section is optional. If provided, UBOS will set up the Site to be only accessible via HTTPS. UBOS will also automatically redirect incoming HTTP requests to their HTTPS equivalent.
letsencrypt
If true, obtain a certificate from LetsEncrypt, and set up the Site with it. Also start an automatic renewal process.
key (if not provided and not letsencrypt, auto-generate one)
The key for the tls Site. Only shown to the root user.
crt (if not provided and not letsencrypt, create a self-signed on)
The certificate for the tls Site as issued by your certificate authority, plus the certificate chain of your certificate authority, concatenated into one file. Only shown to the root user.
cacrt (optional)
If you use TLS client authentication (not common), the certificate chain of the certificate authorities that your TLS clients are using. Only shown to the root user.
wellknown (optional)
This section is optional. It contains the data for “well-known” files that your Site may be using. In this section, each key-value pair represents an entry into the Site’s /.well-known/ Context Path, with the key being the name of the file and the value being a structure with the following potential members:
value
Static file content if there is; the value may be encoded.
encoding
If given, base64 is the only valid value. It indicates that the value of value is provided using Base64 encoding and needs to be decoded first. This is useful for entries such as favicon.ico.
status
HTTP status code to return when accessed. This may only be specified when a location is provided, and the value must be a HTTP redirect status code, such as “307”. When location is provided, the default is “307” (Temporary Redirect).
location
Value for an HTTP Redirect header when accessed. This is mutually exclusive with value: only one of these two may be provided.
prefix
Only permitted for an entry whose key is robots.txt and for which no value has been provided. See discussion below.

For all keys other than robots.txt, the values provided in the Site JSON override any values that may have been provided by the Apps deployed to that Site. Conversely, if the Site JSON does not specify a certain key, but an App deployed to this Site does, the App’s will be used (more details are described in UBOS Manifest). If multiple Apps define the same key, the value from the App defined earlier in the Site JSON’s list of AppConfigurations takes precedence over later ones.

If a value is provided for the key robots.txt, this value will be used. If not, the value for the robots.txt content is constructed by concatenating:

  • the value of prefix in the Site JSON, if such a value is given;

  • a catch-all User-Agent line

  • all Allow/Disallow statements specified by the Apps (more details are described in UBOS Manifest).

Note that UBOS will automatically make the content of the historic files robots.txt, favicon.ico and sitemap.xml available both at the root of the Site and in the .well-known sub-directory.

AppConfigurations

Each member of the appconfigs array is a JSON hash with the following entries:

appconfigid (required)
A unique identifier for the AppConfiguration. This is generally an a followed by 40 hex characters. E.g. a7d74fb881d43d12ff0ba4bd2ed39a98e107eab8c.
context (optional)
The context path, from the root of the Site, where the AppConfiguration will run. For example, if you want to run Wordpress at http://example.org/blog, the Context Path would be /blog (no trailing slash). If you want to run an App at the root of the Site, specify an empty string. If this field is not provided, UBOS will use the App’s default Context Path defined in the App’s UBOS Manifest.
isdefault (optional)
If provided, the value must be boolean true. This instructs UBOS to automatically redirect clients from the root page of the Site to this AppConfiguration. If not provided, UBOS will show the installed Apps at the root page of the Site.
appid (required)
The package identifier of the App to be run. For example: wordpress.
accessoryids (optional)
If provided, this entry must be a JSON array, containing one or more package identifiers of the Accessories to be run for this installation of the App. For example: [ 'wordpress-plugin-webmention' ]
customizationpoints (optional)
If provided, this entry must be a JSON hash, providing values for Customization points section of the App and/or Accessories at this AppConfiguration. They keys in this JSON hash are the package names of the packages installed at this AppConfiguration, i.e. the package name of the App, and any additional Accessories. (By doing this, there cannot be any namespace collisions between Customization Points defined in the App and the Accessory).

The value for each package is again a JSON hash, with the name of the Customization Point as the key, and a JSON hash as a value. Typically, this last JSON hash only has a single entry named value, whose value is the value of the Customization Point. For example:

"customizationpoints" : {
  "wordpress" : {
    "title" : {
      "value" : "My blog"
    }
  }
}