Documentation:

TermsΒΆ

To avoid confusion, here is a glossary of terms that we use for UBOS.

App

On UBOS, an App is a software application that provides direct value to the user without any further additions, integrations or customizations. Apps generally have software dependencies only on Packages provided as part of UBOS.

UBOS Apps are typically web Apps, i.e. Apps whose primary user interface is presented using a web browser. Some examples for UBOS Apps are:

  • Wordpress (blogging and publishing)
  • A house monitoring application, accessible over http or https.

One Device can generally have many installed Apps, distributed over several Sites and AppConfigurations.

Middleware components (e.g. databases) are not considered Apps because the user generally does not directly interact with them.

Accessory

An Accessory on UBOS is a software module that adds to or modifies the functionality of an App. Accessories includes things such as plugins, themes, skins, extensions, add-ons and the like. UBOS uses the term “Accessory” as a consistent, common term for all of those.

Examples for what UBOS would call Accessories are:

  • themes or skins that change the graphic layout of Wordpress;
  • a module that requires users to fill out a captcha before they can register for a wiki;
  • a module that adds a Facebook Like button to an App.
AppConfigId

UBOS identifies each App installed at a particular Site with a unique identifier, such as aa6b76deec72fc2e86c812372e5922b9533ca2d58. UBOS commands that refer to a particular installation of an App generally require that the corresponding AppConfigId is specified. This is particularly important if a Device has several installations of the same App, such as at different Sites and AppConfigurations.

To determine an AppConfigId, execute:

% sudo ubos-admin listsites

Because the AppConfigId is long and unwieldy, you can alternatively use only its first few characters, as long as they are unique on your host and you append three periods at the end. For example, if there is no other App installed on your device whose AppConfigId starts with aa, you can use aa... as a shorthand.

AppConfiguration

The installation of an App at a particular Site (aka virtual host) with a certain Context Path.

For example, if a Device runs the two virtual hosts example.com and example.net, and Wordpress is installed at http://example.com/blog/, at http://example.com/notes/ and at the root of https://example.net/, the Device runs three AppConfigurations. If can also run several other AppConfigurations for other Apps. Each of the AppConfigurations usually has its own database, data storage, set of Accessories and Customization Points.

AppConfigurations are identified through AppConfigIds.

AppConfigItem
A file, directory, systemd service, database or other item that needs to be provisioned to deploy an AppConfiguration. AppConfigItems are defined in an App‘s or Accessory‘s UBOS Manifest JSON.
Arch Linux
A rolling-release GNU/Linux distribution developed at http://archlinux.org/ and ported to various ARM architectures at http://archlinuxarm.org/ .
Context Path
The “file” part of a URL to which an App is deployed, without a trailing slash. For example, if an App has been deployed to URL http://example.com/blog/, its Context Path would be /blog. If it were deployed to the root of the Site, the Context Path would be the empty string.
Customization Point

A variable whose value can be customized by the user. For example, an App might allow the user to configure the title of the App upon installation. In this case, the App might declare a Customization Point called title in its UBOS Manifest. It may or may not specify a default value.

The user must (if a Customization Point does not have a default value) or can (if it does have a default value) specify a value for the Customization Point in their Site JSON. That way, each installation of the App can have a different title, for example.

Depot
The site http://depot.ubos.net/ through which UBOS Packages are distributed. The UBOS Depot hosts several repositories in several release channels.
Device
Any physical or virtualized computer running UBOS. This could be a Raspberry Pi, an x86 server, an instance on Amazon EC2 or a virtual machine on your desktop with virtualization software such as VirtualBox or VMWare.
Flock
See Shepherd.
Home Server
A computer that is primarily accessed over the network, and fully owned by the person who purchased it. For example, a Raspberry Pi running a web application that allows users to control the lights in their house from a web browser would be a Home Server. As a counter-example, if users could control the lights in their house from a web browser connecting to some vendor’s website, this may involve a “server” in their house, but not one they control.
Indie Application
A web application that can be installed on hardware, or on a hosting provider of the user’s choosing. Contrast with a typical website were the user does not have this choice.
Indie IoT
The part of the Internet of Things that is independently owned and operated. Contrast with “Overlord IoT”. For example, the NEST thermostat is not part of the Indie IoT (Google hermetically seals the device, and siphons the data before the “owner” of the device sees it), while a similar product that kept data local and allowed the owner to modify it at will would be part of the Indie IoT.
Letsencrypt
A certificate authority that provides free SSL/TLS certificates accepted by most browsers. See https://letsencrypt.org/.
Multicast DNS (mDNS)
The multicast DNS system allows users to use certain human-friendly hostnames (like ubos-pc.local) on local-area networks without having to configure DNS servers.
Network Configuration
In UBOS, a Network Configuration is a set of active network interfaces, their configuration, and the configuration of associated services such as DNS, firewall, and the like.
Package
A set of code components, and other files that logically belong together. For example, the wordpress Package contains all code specific to Wordpress, but no code that might also be used by other packages. Such other code, e.g. PHP, would be contained in a separate Package.
Personal Server
See Home Server.
PKGBUILD
The build script for creating a UBOS or Arch Linux Package. The Arch Linux wiki has a good description.
Release Channel
A maturity level for an UBOS release. See also UBOS build and release process. UBOS is developed on channel red, which contains bleeding-edge, untested “alpha” quality code. Channel yellow corresponds to traditional “beta” code, while green is the production channel. End users almost always will subscribe to green, while developers will do most of their work on red and yellow.
Repository
A collection of packages. For example, the UBOS tools Repository contains tools useful to the developer, but not to the end user. By default, UBOS Devices do not use the tools repository, but= developers can easily add it to take advantage of the provided development tools.
Role
To successfully deploy a functioning App, all AppConfigItems in all Roles specified in the App‘s UBOS Manifest must be deployed. Each Role relates to a particular “tier” in a multi-tiered web architecture implemented with a particular service, such as “Apache2” or “MySQL”. Currently, UBOS only supports collocation of all Roles on the same Device. (See also Roles section.)
Rolling Release
Most operating system distros release a major release every couple of years with major new features, and then minor updates on a regular basis. A distro using Rolling Releases, such as UBOS, provides updates on a continuous basis without major jumps. This allows user devices to be more up-to-date more of the time, and avoids often error-prone major upgrades.
Shepherd
The UBOS Shepherd is the person who administers one or more Devices running UBOS. These Devices are called the Flock. The Shepherd uses a USB stick, called the UBOS Staff, to configure each Device in the Flock by booting it while the Staff has been inserted into the Device‘s USB port. Configuration information picked up by the UBOS Device will remain valid until the Shepherd reboots the Device with the Staff present again.
Site
Short for website; all the Apps and functionality at the same hostname, e.g. virtual host. Sites are referred to by SiteIds.
Site JSON

A JSON file that contains all meta-data about a Site, including its hostname, whether it uses TLS and potentially the TLS keys and certificates, which Apps are installed at which relative URLs, and so forth. To obtain the full Site JSON for a particular installed Site with SiteId <siteid>, execute:

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

To deploy or update a deployed Site to the configuration contained in a Site JSON file called <site-json-file>, execute:

% sudo ubos-admin deploy --file <site-json-file>
SiteId

UBOS identifies sites with a unique identifier, such as s4100f3ed79b845dc04a974c0144f5c5b2f81face. UBOS commands that refer to a particular Site generally require that the Site‘s SiteId is specified. (See also AppConfigId.)

To determine a Site‘s SiteId, execute:

% sudo ubos-admin listsites

Because the SiteIds is long and unwieldy, you can alternatively use only its first few characters, as long as they are unique on your host and you append three periods at the end.

For example, if there is no other Site installed on your host whose SiteId starts with s41, you can use s41... as a shorthand.

Many commands also accept the current hostname of the Site instead of the SiteId.

Staff
See Shepherd.
UBOS Manifest
Meta-data about an App or Accessory beyond the meta-data provided by PKGBUILD.
UBOS Manifest JSON
A JSON file that contains the UBOS Manifest.