The scripts
App scripts are the essential logic defining what happens when an app is installed, removed, upgraded, backuped, or restored. They are written in Bash which is the same stuff you type in interactive mode in a terminal, though we added a bunch of custom YunoHost functions that we call helpers to standardize many common operations - for example adding the nginx configuration.
Note that starting from packaging v2, the logic or what happens when an app is installed, etc. is also contained partially in the resource configuration in the manifest.toml.
In the scripts folder of an app, you can expect to find:
manifest.toml
scripts
├── _common.sh # Some "common" definition, typically custom helpers
│ # or global variables used accross all scripts
├── install # The install procedure
├── remove # The remove procedure
├── backup # The backup procedure - in fact it only "declares" what should be backed up.
│ # No actual real backup happens at this point except dumping SQL databases
├── restore # The restore procedure
├── change_url # Some apps do also provide a change url script, which corresponds to changing
│ # the URL endpoint of the app, which may be as simple as changing
│ # the nginx conf, or may involve significant changes in the app DB
└── upgrade # The upgrade procedure
Here is an example of the simple install script for the helloworld app:
#!/bin/bash
# This is where we load the official YunoHost helpers
source /usr/share/yunohost/helpers
#=================================================
# DOWNLOAD, CHECK AND UNPACK SOURCE
# This is where we would usually fetch the .tar.gz archive
# from the upstream and extract it into our local install dir
#=================================================
# At the beginning of each major operation, we call this helper
# that creates a progress bar
ynh_script_progression --message="Setting up source files..." --weight=1
echo "Hello world!" > $install_dir/index.html
chown -R www-data: "$install_dir"
#=================================================
# NGINX CONFIGURATION
# This is where the nginx conf snippet for the app is created using the
# configuration template provided in conf/nginx.conf
# and added to /etc/nginx/conf.d/$domain.d/$app.conf
#=================================================
ynh_script_progression --message="Configuring nginx web server..." --weight=1
ynh_add_nginx_config
Note that the scripts are run with the set -eu options (except for the remove script), which means that any failing command or use of non-existing variable will trigger an error and stop the script execution.
Variables available in a script context
Special variables are automatically defined in the context of a script:
$appis the app ID. It will typically be the ID from the app's manifest.toml, for examplehelloworld, but will behelloworld__2,__3etc for multi-instance installs.- During install, answers to install questions are automatically available as bash variables. Typically,
$domainand$pathwill contain the answers to the default install questions assuming they are defined in themanifest.toml. Answer values associated to any custom install questions will be available the same way, e.g.$prefered_petfor the custom question[install.prefered_pet]that would be defined in the manifest. Note that - apart from special questions such asinit_main_permissionor user-provided passwords - they are also automatically saved as settings (cf. next section). - During other scripts, all app settings are also loaded and automatically available.
- Note that some settings are automatically created/updated by app ressources. For example, the
install_dirsetting will automatically be available too and corresponds to typically/var/www/$app - In the
change_urlcontext, variables callednew_domain,new_path,old_domain,old_pathwill be available, as well aschange_domainandchange_pathequal to0(false) or1(true) depending if the domain / path changed
Setting system
Application often need to store long term information in between scripts triggered by the admin. For this, YunoHost has a key-value store for each application called "setting" and is stored in /etc/yunohost/apps/$app/settings.yml.
Apps can interact with this key value store in this way:
# Retrieve a setting into variable "db_name"
db_name=$(ynh_app_setting_get --app=$app --key=db_name)
# Update a setting
ynh_app_setting_set --app=$app --key=db_name --value=$db_name
Helper system
We call helpers a set of custom bash function created by the YunoHost project to standardize common operations accross all apps. They are all prefixed with ynh_. The full list and documentation of these helpers is available on this page. Some of these helpers are now partially obsolete as they are now handled by the core via app resources.
Here is the list of the major ones:
ynh_app_setting_get/ynh_app_setting_setynh_script_progressionynh_setup_source- nginx:
ynh_add_nginx_config/ynh_remove_nginx_config - php:
ynh_add_fpm_config/ynh_remove_fpm_config - systemd:
ynh_add_systemd_config/ynh_remove_systemd_config - fail2ban:
ynh_add_fail2ban_config/ynh_remove_fail2ban_config - custom:
ynh_add_config - nodejs:
ynh_install_nodejs/ynh_use_nodejs ynh_exec_warn_lessynh_local_curlynh_secure_removeynh_backup/ynh_restore_file
Configuration/template system
App scripts will often need to create a bunch of configuration files.
Configuration templates are canonically stored provided in the conf/ folder of the app, such as nginx.conf, extra_php-fpm.conf, systemd.conf, or some-custom-app-conf.env ...
In these templates, you can use the syntax __FOOBAR__ which will automatically be replaced by the variable $foobar during runtime, when the conf is installed via the ynh_add_*_config helpers.
For example, an app's NGINX conf snippet may look like:
# The next line starting with '#sub_path_only' is automatically uncommented only when $path is not /
#sub_path_only rewrite ^__PATH__$ __PATH__/ permanent;
location __PATH__/ {
alias __INSTALL_DIR__/;
# Some headers and tweaks
}
App sources
App sources were historically defined in conf/app.src files containing the URL + checksum of assets to download.
This is now integrated in manifest.toml using the sources resource, which pre-download the assets prior to entering the install or upgrade scripts. The sources can then be effectively deployed using ynh_setup_source.
For example, for YesWiki, the sources are defined in manifest.toml using:
[resources.sources.main]
url = "https://github.com/YesWiki/yeswiki/archive/refs/tags/v4.4.0.tar.gz"
sha256 = "5ceb12d225c20de2ba3cb4ce483348ed1a8ad5b1789d4f4f8f89dc4871524007"
More infos on the source resource in the resource system documentation.