Roles section
/docs/development/reference-gears/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
orpostgresql
-
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 themysql
role);perlscript
: a Perl script that needs to be run;sqlscript
: a SQL script that needs to be run (only use this for themysql
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 thename
or currentnames
entry.$2
: it will be replaced with the file name (without directories) of thename
or currentnames
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, and 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
|
The string "keep" . All other values are reserved. Setting this requires
setting the retentionbucket as well.
|
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 |
file |
perl |
sql |
symlink |
systemd- |
systemd- |
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 themysql
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 atexample.com
, by default Wordpress will be accessible athttp://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. Usefixedcontext
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
orwebfinger
entries (see additional fields below). encoding
- If given,
base64
is the only valid value. It indicates that the value ofvalue
is provided using Base64 encoding and needs to be decoded first. This is useful for entries such asfavicon.ico
. location
- Value for the HTTP
Location
header when accessed. This is mutually exclusive withvalue
: only one of these two may be provided. This field must not be used byrobots.txt
orwebfinger
entries (see below). This value may use variables (as described in variables.d), 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”. Whenlocation
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 individualAllow:
entries for a compositerobots.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 becomeAllow: /myapp/assets/
if the App has been deployed at context path/myapp
. disallow
- Just like
allow
, but forDisallow:
content for a compositerobots.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
When an AppConfiguration with an App and one ore more Accessories is deployed, generally the AppConfigItems of the App are deployed first, followed by the AppConfigItems of one Accessory at a time in the sequence the Accessories were defined in the Site JSON file.
Then, any installer or upgrader scripts are run in the sequence they were defined in the UBOS Manifest, with those defined by the App before those defined by the Accessories.
Undeploying the AppConfiguration occurs in the opposite sequence.
However, sometimes it is necessary to deviate from this default sequence, in particular if the App runs a daemon that requires that all Accessories have been deployed already at the time it starts.
For example, if an App runs a Java daemon with Accessories that contribute optional JARs, and the daemon only scans the available JARs at the time it first starts up, clearly the daemon can only start all Accessories have been deployed.
In order to support this (fairly rare) situation, the relevant
AppConfigItems (in the example, of type systemd-service
that
starts the daemon) can be marked with an extra entry:
"phase" : "suspendresume"
This will cause the AppConfigItem to be skipped on the first pass when installing AppConfigItems, and only process it on a second pass that occurs after the Accessories have all been deployed.
No other values for phase
are currently defined.
Status of the AppConfiguration
Status: proposed
Apps may optionally declare an executable or script that, when invoked, reports status information of the AppConfiguration on which it is applied. This status information is provided in JSON in a format defined in Format of the App Status JSON.
To declare such an executable or script, add the following JSON fragment in the apache2
role in its App’s UBOS Manifest JSON, assuming the Perl script status.pl
in directory ${appconfig.apache2.dir}
should be invoked:
"status" : {
"source" : "status.pl",
"type" : "perlscript"
}
Alternatively, the exec
type can be used:
"status" : {
"source" : "status.sh",
"type" : "exec"
}
The script or executable will be invoked with the same arguments as other scripts or
executables specified in the UBOS Manifest JSON, but the value for operation
is
status
.
This script or executable is only invoked while the App has been deployed and is supposed to be operational. It is not invoked at any other time.