Roles section

/docs/gears/developer/reference/manifest/roles/

The roles section in an UBOS Manifest defines how the App or Accessory needs to be deployed and related information. For example, the roles section defines:

which files or directories need to be created in the file system;
which databases need to be provisioned with which permissions;
which directories or databases need to be backed up;
which scripts to run after installation, before uninstallation, or for a version upgrade.

The roles section is structured by roles. Currently supported roles are:

apache2: information related to the web tier;
tomcat8: information related to the Java :term:Apps <App> running on Tomcat (if applicable);
mysql: information related to MySQL databases (if applicable);
postgresql: information related to Postgresql databases (if applicable);
generic: information not related to any of the other tiers (this is rare).

Generally, upon installation of an App or Accessory, the roles are processed in this sequence:

mysql or postgresql
generic
tomcat8
apache2

Upon uninstallation of an App or Accessory, the roles are processed in the opposite sequence.

Here are common fields for all roles:

Common fields

Depends

When the App or Accessory is deployed for this role, the field depends identifies required packages. Often, these dependencies could also be listed in the package’s PKGBUILD file, but this additional field allows the declaration of dependencies that are only required if this role is used.

Example:

"apache2" : {
  "depends" : [ "php-apache", "php-gd" ],
  ...

AppConfigItems

This section captures the items that need to be put in place before a deployment of an App or Accessory is functional. These items can be things such as files, directories, symbolic links, or databases; but also scripts that need to be run.

For example, in the apache2 role of an App the following appconfigitems section may be found:

"appconfigitems" : [
  {
    "type"         : "file",
    "name"         : "index.php",
    "source"       : "web/index.php",
  },
  {
    "type"         : "file",
    "name"         : "config.php",
    "template"     : "tmpl/config.php.tmpl",
    "templatelang" : "varsubst"
  },
  {
    "type"         : "symlink",
    "name"         : "gladiwashere.php",
    "source"       : "web/gladiwashere.php"
  }
]

Here, three items need to be put in place: two files, and a symbolic link. The following AppConfigItem types are currently supported:

directory: a directory to be created;
directorytree : a recursive directory tree, copied from somewhere else;
file: a file, created by copying another file, or processing another file (see below);
database: a database that needs to be created (only use this for database roles such as the mysql role);
perlscript: a Perl script that needs to be run;
sqlscript: a SQL script that needs to be run (only use this for the mysql role);
symlink: a symbolic link;
systemd-service: a systemd service to be running while the AppConfiguration is deployed;
systemd-timer: a systemd timer to be active while the AppConfiguration is deployed;
tcpport: a TCP port needs to be reserved for the exclusive use of this AppConfiguration;
udpport: a UDP port needs to be reserved for the exclusive use of this AppConfiguration.

The field name is the name of the file, directory, database, systemd service or timer to be created or operated on. names can be used as a shortcut for several AppConfigItems to which the same other settings apply.

The field template identifies a file or directory that is to be used as a template for creating the new item. The corresponding field templatelang states how the template should be used to create the item. In the example above, the varsubst (“variable substitution”) algorithm is to be applied. (See Variables available at deploy or undeploy and Scripts in UBOS Manifests.)

The field source refers to a file that is the source code for the script to be run, or the destination of the symbolic link. (Think of the original file that is either being copied, run, or pointed to with the symbolic link.)

The source field in case of directorytree, file and symlink may contain:

$1: it will be replaced with the value of the name or current names entry.
$2: it will be replaced with the file name (without directories) of the name or current names entry.

The following table shows all attributes for AppConfigItems that are defined:

JSON entry	Description	Relative path context	Mutually exclusive with
`charset`	Default character set for SQL database (default: Unicode)	N/A	N/A
`collate`	Default collation set for SQL database	N/A	N/A
`delimiter`	Delimiter for SQL scripts (default: `;`)	N/A	N/A
`dirpermissions`	A string containing the octal number for the `chmod` permissions for directories in this directory hierarchy (default: `0755`)	N/A	N/A
`filepermissions`	A string containing the octal number for the `chmod` permissions for files in this directory hierarchy (default: `0644`)	N/A	N/A
`gname`	The name of the Linux group that this item should belong to (default: `root`).	N/A	N/A
`name`	The name of the created file, directory, symlink, or root of the directory tree, or the symbolic name of a database, or port.	`${appconfig.apache2.dir}`	`names`
`names`	The names of the created files, directories, symlinks, or roots of the directory trees if more than one item supposed to be processed with the same rule.	`${appconfig.apache2.dir}`	`name`
`permissions`	A string containing the octal number for the `chmod` permissions for this file or directory (default: `"0644"` for files, `"0755"` for directories).	N/A	N/A
`privileges`	SQL privileges for a database.	N/A	N/A
`retentionbucket`	If given, captures that this item contains valuable data that needs to be preserved, e.g. when a backup is performed. This field gives it a symbolic name that becomes a named section in backup files. Setting this requires setting the `retentionpolicy` as well.	N/A	N/A
`retentionpolicy`	There are two supported values: `keep`: Indicates that the item needs to be backed up when a Backup is made, and restored when a Backup is restored. `restore`: Indicates that the item needs to be restoed when a Backup is restored, but not backed up when a Backup is made. This is typically used to obsolete a bucket from one version of an App to another: after restoring, an upgrade script can copy the data to another place, optionally transforming it, which can be a new bucket.	N/A	N/A
`source`	The name of a file to copy (or execute) without change.	`${package.codedir}`	`template`
`template`	The name of a template file that will be copied after being processed according to the value of `templatelang`.	`${package.codedir}`	`source`
`templatelang`	Specifies the type of template processing to be performed on the content of `template`.	N/A	`source`
`uname`	The name of the Linux user account that should own the created item (default: `root`).	N/A	N/A

This table shows which attributes apply to which types of AppConfigItems:

JSON entry	`database`	`exec`	`directory`	`directory tree`	`file`	`perl script`	`sql script`	`symlink`	`systemd- service`	`systemd- timer`	`tcpport`	`udpport`
`delimiter`							Y
`dirpermissions`			Y	Y
`filepermissions`			Y	Y
`gname`			Y	Y	Y			Y
`name`	Y		Y	Y	Y		Y	Y	Y	Y	Y	Y
`names`			Y	Y	Y			Y
`permissions`					Y
`privileges`	Y
`retentionbucket`	Y		Y		Y
`retentionpolicy`	Y		Y		Y
`source`		Y		Y	Y	Y	Y	Y
`template`					Y		Y
`templatelang`					Y		Y
`uname`			Y	Y	Y			Y

Installers, Uninstallers, Upgraders

These fields identify scripts to be run when certain events occur:

field installers is processed when the App or Accessory is deployed;
field upgraders is processed after an App or Accessory has been deployed and data has been restored that potentially must be migrated to work with the current version of the App or Accessory.

Note that during software upgrades, deployment and undeployment may occur as well (see Command: ubos-admin update).

Each of these fields points to an array. Each of the elements in the array is a separate script that will be run in the sequence listed.

Here is an example for installers in the mysql role of an App that uses MySQL:

"installers" : [
  {
    "name"   : "maindb",
    "type"   : "sqlscript",
    "source" : "mediawiki/maintenance/tables.sql"
  }
]

When this section is processed, UBOS will run the script mediawiki/maintenance/tables.sql of type sqlscript against the database whose symbolic name is maindb.

Supported types are:

sqlscript: a SQL script (but only for the mysql role)
perlscript: a Perl script

Apache2 role

The apache2 role knows additional fields.

Context

Web Apps must specify one of the following two fields:

defaultcontext: the relative URL path at which the App is installed by default. For example, Wordpress may have a defaultcontext of /blog, i.e. if the user installs Wordpress at example.com, by default Wordpress will be accessible at http://example.com/blog. This field is to be used if the App is able to be installed at any relative URL, but this is the default.
fixedcontext: some web Apps can only be installed at a particular relative URL, or only at the root of a Site. Use fixedcontext to declare that relative URL.

Transport-level security (TLS) required

Some Apps require that they be accessed via HTTPS only, using SSL/TLS, and will refuse to work over HTTP. Such Apps need to declare this requirement, so UBOS can prevent that they are deployed to an HTTP-only site. To declare this requirement, use this JSON fragment:

"requirestls" : true

If not given, the default for this field is assumed to be false.

Wildcard hostname not supported

Some Apps require to know the hostname through which they are accessed, and cannot be run at the Wildcard hostname. To declare this requirements, use this JSON fragment:

"allowswildcardhostname" : false

If not given, the default for this field is assumed to be true.

Apache modules

apache2modules is a list of names of Apache2 modules that need to be activated before the App or Accessory can be successfully run. Here is an example:

"apache2modules" : [
  "php7"
]

This declaration will make sure that the php7 module is active in Apache2; if not yet, UBOS will activate it and restart Apache2 without any further work by the App or Accessory.

Note that the apache2 role still needs to declare a dependency on php7; apache2modules does not attempt to infer which packages might be needed.

PHP modules

phpmodules is a list of names of PHP modules that need to be activated before the App or Accessory can be successfully run. Here is an example:

"phpmodules" : [
  "gd"
]

This declaration will make sure that the PHP module gd has been activated; if not, UBOS will activate it and restart Apache2.

Note that the apache2 role still needs to declare a dependency on php-gd; apache2modules does not attempt to infer which packages might be needed.

Contributions to the site’s “well-known”

Sites may publish certain “well-known” files, such as robots.txt or the content of directory .well-known below the root of the Site. Subject to certain conflict resolution rules described in Site JSON, an App deployed to a Site may request to augment those entries.

For that purpose, the wellknown entry may be specified. Here is an example:

"wellknown" : {
  "carddav" : {
    "value" : "..."
  },
  "caldav" : {
    "location" : "caldav.php",
    "status" : "302 Found"
  },
  "webfinger" : {
    "proxy" : "http://localhost:1234/webfinger"
  }
}

In wellknown, 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 JSON object with the following potential members (Note the special rules for robots.txt and webfinger described below):

value: Static file content if there is; the value may be encoded. This field must not be used by robots.txt or webfinger entries (see additional fields below).
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.
location: Value for the HTTP Location header when accessed. This is mutually exclusive with value: only one of these two may be provided. This field must not be used by robots.txt or webfinger entries (see below). This value may use variables (as described in Variables available at deploy or undeploy), which UBOS will replace during deployment.
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).
allow: Only permitted for an entry whose key is robots.txt. This field must have a value of type JSON array. The members of that array are individual Allow: entries for a composite robots.txt file. Each member is prefixed by the content path to the AppConfiguration to which this App has been deployed. For example, if one of the values is /assets/, it will become Allow: /myapp/assets/ if the App has been deployed at context path /myapp.
disallow: Just like allow, but for Disallow: content for a composite robots.txt file.
proxy: Only permitted for an entry whose key is webfinger. This field must have a value of type string, containing a fully-qualified http or https URL (variable $(site.protocol) may be used). This specifies that UBOS, when a client requests the Site’s well-known webfinger URL, should access the given URL, and semantically merge the resulting JSON files obtained from all App’s defining a well-known proxy at this Site. This enables multiple App’s deployed to the Site to all publish their contribution to the Site’s webfinger well-known. This value may use variables (as described in Variables available at deploy or undeploy), which UBOS will replace during deployment.

Phases

Note

Redesigned 2026-05.

When an AppConfiguration with an App and one ore more Accessories is deployed, it may be necessary to deviate from the default sequence in which AppConfigItems and Installers and Upgraders are run. To support this, the JSON entries in the appconfigitems, installers and upgraders arrays support an optional extra field called phase.

AppConfigItems and post-deploy scripts (installers and upgraders) can be marked with an extra entry:

"phase" : <PHASE>

The supported values for <PHASE> are, for AppConfigItems:

Not given, or `default`	The default.
`after-accessories`	Delayed until the default phase of all Accessories has been processed.
`after-installers-upgraders`	Delayed until the installers or upgraders have been run.

The supported values for <PHASE> are, for install and upgrade scripts:

Not given, or `default`	The default.
`after-accessories`	Delayed until all `installers` and `upgraders` of all Accessories have been processed.
`after-resume`	Delayed until the Site has been resumed and it is resposive to users.

The sequence is as follows:

1. Phase PHASE_APPCONFIGITEM_DEFAULT:

Use AppConfigItems to put files and directories into the right places, provision ports, databases etc.
The App’s AppConfigItems are deployed first, followed by each Accessory’s AppConfigItems. For example:
- PHP files for WordPress

2. Phase PHASE_APPCONFIGITEM_AFTER_ACCESSORIES:

Sometimes an App can only create a particular AppConfigItem once all the Accessories' AppConfigItems are present first. For example:
- It may need to create a file that contains all the names of the installed Accessories, or all files in certain directories installed by all installed Accessories. This cannot be done at the beginning.
- Or, an App daemon can only be run once all Accessory code is in place.

3. Phase PHASE_POSTDEPLOY_DEFAULT:

Now we need to populate the database (upon install) or migrate the database (upon upgrade). For this, we run have the post-deploy scripts: first that of the App, then those of the Accessories. Example:
- Any App that requires a relational database.

4. Phase PHASE_APPCONFIGITEM_AFTER_INSTALLERS_UPGRADERS:

Some AppConfigItems can only be run once the database has been initialized or upgraded. For example:
- a daemon.

5. Phase PHASE_POSTDEPLOY_AFTER_ACCESSORIES:

Some part of an App’s installation or upgrade may depend on all Accessories first be installed or upgraded. That’s what this is for. Example:
- Nextcloud’s “add missing database indices” admin command

6. Phase PHASE_POSTDEPLOY_AFTER_RESUME:

This last part are installers or upgraders that can only run once the App is fully installed. Example:
- A web app whose database is intended to be initialized by the user with a web browser. This script would simulate that.