App resources

Doc auto-generated by this script on 13/11/2024 (YunoHost version 12.0.7)

Apt

Create a virtual package in apt, depending on the list of specified packages that the app needs. The virtual packages is called $app-ynh-deps (with _ being replaced by - in the app name, see ynh_install_app_dependencies)

Example

[resources.apt]
packages = ["nyancat", "lolcat", "sl"]

# (this part is optional and corresponds to the legacy ynh_install_extra_app_dependencies helper)
extras.yarn.repo = "deb https://dl.yarnpkg.com/debian/ stable main"
extras.yarn.key = "https://dl.yarnpkg.com/debian/pubkey.gpg"
extras.yarn.packages = ["yarn"]

Properties

• packages: List of packages to be installed via apt
• packages_from_raw_bash: A multi-line bash snippet (using triple quotes as open/close) which should echo additional packages to be installed. Meant to be used for packages to be conditionally installed depending on architecture, debian version, install questions, or other logic.
• extras: A dict of (repo, key, packages) corresponding to "extra" repositories to fetch dependencies from

Provision/Update

• The code literally calls the bash helpers ynh_install_app_dependencies and ynh_install_extra_app_dependencies, similar to what happens in v1.
• Note that when packages contains some phpX.Y-foobar dependencies, this will automagically define a phpversion setting equal to X.Y which can therefore be used in app scripts ($phpversion) or templates (__PHPVERSION__)

Deprovision

• The code literally calls the bash helper ynh_remove_app_dependencies

Data Dir

Creates a directory to be used by the app as the data store directory, typically where the app multimedia or large assets added by users are located. The corresponding path is stored in the settings as data_dir. This resource behaves very similarly to install_dir.

Example

[resources.data_dir]
# (empty - defaults are usually okay)

Properties

• dir: (default: /home/yunohost.app/__APP__) The full path of the data dir
• subdirs: (default: empty list) A list of subdirs to initialize inside the data dir. For example, ['foo', 'bar']
• owner: (default: __APP__:rwx) The owner (and owner permissions) for the data dir
• group: (default: __APP__:rx) The group (and group permissions) for the data dir

Provision/Update

• if the dir path changed and a folder exists at the old location, the folder will be mv'ed to the new location
• otherwise, creates the directory if it doesn't exists yet
• create each subdir declared and which do not exist already
• (re-)apply permissions (only on the folder itself and declared subdirs, not recursively)
• save the value of dir as data_dir in the app's settings, which can be then used by the app scripts ($data_dir) and conf templates (__DATA_DIR__)

Deprovision

• (only if the purge option is chosen by the user) recursively deletes the directory if it exists
• also delete the corresponding setting

Legacy management

• In the past, the setting may have been called datadir. The code will automatically rename it as data_dir.
• As explained in the 'Provision/Update' section, the folder will also be moved if the location changed

Database

Initialize a database, either using MySQL or Postgresql. Relevant DB infos are stored in settings $db_name, $db_user and $db_pwd.

NB: only one DB can be handled in such a way (is there really an app that would need two completely different DB ?...)

NB2: no automagic migration will happen in an suddenly change type from mysql to postgresql or viceversa in its life

Example

[resources.database]
type = "mysql"   # or : "postgresql". Only these two values are supported

Properties

• type: The database type, either mysql or postgresql

Provision/Update

• (Re)set the $db_name and $db_user settings with the sanitized app name (replacing - and . with _)
• If $db_pwd doesn't already exists, pick a random database password and store it in that setting
• If the database doesn't exists yet, create the SQL user and DB using ynh_mysql_create_db or ynh_psql_create_db.

Deprovision

• Drop the DB using ynh_mysql_remove_db or ynh_psql_remove_db
• Deletes the db_name, db_user and db_pwd settings

Legacy management

• In the past, the sql passwords may have been named mysqlpwd or psqlpwd, in which case it will automatically be renamed as db_pwd

Install Dir

Creates a directory to be used by the app as the installation directory, typically where the app sources and assets are located. The corresponding path is stored in the settings as install_dir

Example

[resources.install_dir]
# (empty - defaults are usually okay)

Properties

• dir: (default: /var/www/__APP__) The full path of the install dir
• owner: (default: __APP__:rwx) The owner (and owner permissions) for the install dir
• group: (default: __APP__:rx) The group (and group permissions) for the install dir

Provision/Update

• during install, the folder will be deleted if it already exists (FIXME: is this what we want?)
• if the dir path changed and a folder exists at the old location, the folder will be mv'ed to the new location
• otherwise, creates the directory if it doesn't exists yet
• (re-)apply permissions (only on the folder itself, not recursively)
• save the value of dir as install_dir in the app's settings, which can be then used by the app scripts ($install_dir) and conf templates (__INSTALL_DIR__)

Deprovision

• recursively deletes the directory if it exists

Legacy management

• In the past, the setting was called final_path. The code will automatically rename it as install_dir.
• As explained in the 'Provision/Update' section, the folder will also be moved if the location changed

Permissions

Configure the SSO permissions/tiles. Typically, webapps are expected to have a 'main' permission mapped to '/', meaning that a tile pointing to the $domain/$path will be available in the SSO for users allowed to access that app.

Additional permissions can be created, typically to have a specific tile and/or access rules for the admin part of a webapp.

The list of allowed user/groups may be initialized using the content of the init_{perm}_permission question from the manifest, hence init_main_permission replaces the is_public question and shall contain a group name (typically, all_users or visitors).

Example

[resources.permissions]
main.url = "/"
# (these two previous lines should be enough in the majority of cases)

admin.url = "/admin"
admin.show_tile = false
admin.allowed = "admins"   # Assuming the "admins" group exists (cf future developments ;))

Properties (for each perm name)

• url: The relative URI corresponding to this permission. Typically / or /something. This property may be omitted for non-web permissions.
• show_tile: (default: true if url is defined) Wether or not a tile should be displayed for that permission in the user portal
• allowed: (default: nobody) The group initially allowed to access this perm, if init_{perm}_permission is not defined in the manifest questions. Note that the admin may tweak who is allowed/unallowed on that permission later on, this is only meant to initialize the permission.
• auth_header: (default: true) Define for the URL of this permission, if SSOwat pass the authentication header to the application. Default is true
• protected: (default: false) Define if this permission is protected. If it is protected the administrator won't be able to add or remove the visitors group of this permission. Defaults to 'false'.
• additional_urls: (default: none) List of additional URL for which access will be allowed/forbidden

Provision/Update

• Delete any permissions that may exist and be related to this app yet is not declared anymore
• Loop over the declared permissions and create them if needed or update them with the new values

Deprovision

• Delete all permission related to this app

Legacy management

• Legacy is_public setting will be deleted if it exists

Ports

Book port(s) to be used by the app, typically to be used to the internal reverse-proxy between nginx and the app process.

Note that because multiple ports can be booked, each properties is prefixed by the name of the port. main is a special name and will correspond to the setting $port, whereas for example xmpp_client will correspond to the setting $port_xmpp_client.

Example

[resources.ports]
# (empty should be fine for most apps... though you can customize stuff if absolutely needed)

main.default = 12345    # if you really want to specify a prefered value .. but shouldnt matter in the majority of cases

xmpp_client.default = 5222  # if you need another port, pick a name for it (here, "xmpp_client")
xmpp_client.exposed = "TCP" # here, we're telling that the port needs to be publicly exposed on TCP on the firewall

Properties (for every port name)

• default: The prefered value for the port. If this port is already being used by another process right now, or is booked in another app's setting, the code will increment the value until it finds a free port and store that value as the setting. If no value is specified, a random value between 10000 and 60000 is used.
• exposed: (default: false) Wether this port should be opened on the firewall and be publicly reachable. This should be kept to false for the majority of apps than only need a port for internal reverse-proxying! Possible values: false, true(=Both), Both, TCP, UDP. This will result in the port being opened on the firewall, and the diagnosis checking that a program answers on that port.
• fixed: (default: false) Tells that the app absolutely needs the specific value provided in default, typically because it's needed for a specific protocol

Provision/Update (for every port name)

• If not already booked, look for a free port, starting with the default value (or a random value between 10000 and 60000 if no default set)
• If exposed is not false, open the port in the firewall accordingly - otherwise make sure it's closed.
• The value of the port is stored in the $port setting for the main port, or $port_NAME for other NAMEs

Deprovision

• Close the ports on the firewall if relevant
• Deletes all the port settings

Legacy management

• In the past, some settings may have been named NAME_port instead of port_NAME, in which case the code will automatically rename the old setting.

Sources

Declare what are the sources / assets used by this app. Typically, this corresponds to some tarball published by the upstream project, that needs to be downloaded and extracted in the install dir using the ynh_setup_source helper.

This resource is intended both to declare the assets, which will be parsed by ynh_setup_source during the app script runtime, AND to prefetch and validate the sha256sum of those asset before actually running the script, to be able to report an error early when the asset turns out to not be available for some reason.

Various options are available to accomodate the behavior according to the asset structure

Example

[resources.sources]

    [resources.sources.main]
    url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.tar.gz"
    sha256 = "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"

    autoupdate.strategy = "latest_github_tag"

Or more complex examples with several element, including one with asset that depends on the arch

[resources.sources]

    [resources.sources.main]
    in_subdir = false
    amd64.url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.amd64.tar.gz"
    amd64.sha256 = "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
    i386.url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.386.tar.gz"
    i386.sha256 = "53c234e5e8472b6ac51c1ae1cab3fe06fad053beb8ebfd8977b010655bfdd3c3"
    armhf.url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.arm.tar.gz"
    armhf.sha256 = "4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865"

    autoupdate.strategy = "latest_github_release"
    autoupdate.asset.amd64 = ".*\\.amd64.tar.gz"
    autoupdate.asset.i386 = ".*\\.386.tar.gz"
    autoupdate.asset.armhf = ".*\\.arm.tar.gz"

    [resources.sources.zblerg]
    url = "https://zblerg.com/download/zblerg"
    sha256 = "1121cfccd5913f0a63fec40a6ffd44ea64f9dc135c66634ba001d10bcf4302a2"
    format = "script"
    rename = "zblerg.sh"

Properties (for each source)

• prefetch : true (default) or false, wether or not to pre-fetch this asset during the provisioning phase of the resource. If several arch-dependent url are provided, YunoHost will only prefetch the one for the current system architecture.
• url : the asset's URL
  • If the asset's URL depend on the architecture, you may instead provide amd64.url, i386.url, armhf.url and arm64.url (depending on what architectures are supported), using the same dpkg --print-architecture nomenclature as for the supported architecture key in the manifest
• sha256 : the asset's sha256sum. This is used both as an integrity check, and as a layer of security to protect against malicious actors which could have injected malicious code inside the asset...
  • Same as url : if the asset's URL depend on the architecture, you may instead provide amd64.sha256, i386.sha256, ...
• format : The "format" of the asset. It is typically automatically guessed from the extension of the URL (or the mention of "tarball", "zipball" in the URL), but can be set explicitly:
  • tar.gz, tar.xz, tar.bz2 : will use tar to extract the archive
  • zip : will use unzip to extract the archive
  • docker : useful to extract files from an already-built docker image (instead of rebuilding them locally). Will use docker-image-extract
  • whatever: whatever arbitrary value, not really meaningful except to imply that the file won't be extracted (eg because it's a .deb to be manually installed with dpkg/apt, or a script, or ...)
• in_subdir: true (default) or false, depending on if there's an intermediate subdir in the archive before accessing the actual files. Can also be N (an integer) to handle special cases where there's N level of subdir to get rid of to actually access the files
• extract : true or false. Defaults to true for archives such as zip, tar.gz, tar.bz2, ... Or defaults to false when format is not something that should be extracted. When extract = false, the file will only be mved to the location, possibly renamed using the rename value
• rename: some string like whatever_your_want, to be used for convenience when extract is false and the default name of the file is not practical
• platform: for example linux/amd64 (defaults to linux/$YNH_ARCH) to be used in conjonction with format = "docker" to specify which architecture to extract for

Regarding autoupdate

Strictly speaking, this has nothing to do with the actual app install. autoupdate is expected to contain metadata for automatic maintenance / update of the app sources info in the manifest. It is meant to be a simpler replacement for "autoupdate" Github workflow mechanism.

The infos are used by this script : https://github.com/YunoHost/apps_tools/blob/main/autoupdate_app_sources/autoupdate_app_sources.py which is ran by the YunoHost infrastructure periodically and will create the corresponding pull request automatically.

The script will rely on the code repo specified in code in the upstream section of the manifest.

The autoupdate.strategy is expected to be constructed like this: latest_<gitforge>_<strategy>

You need to replace the <gitforge> in the strategy name by either github, gitlab, gitea or forgejo, as the autoupdater supports:

• GitHub
• GitLab (official and self-hosted instances)
• Gitea & Forgejo instances

And choose one strategy in the following ones:

• latest_<gitforge>_release : similar to latest_<gitforge>_tag, but starting from the list of releases. Note that it's the only strategy that provides the changelog link in the PR message. Pre- or draft releases are ignored. Releases may have assets attached to them, in which case you can define:
  • autoupdate.asset = "some regex" (when there's only one asset to use). The regex is used to find the appropriate asset among the list of all assets
  • or several autoupdate.asset.$arch = "some_regex" (when the asset is arch-specific). The regex is used to find the appropriate asset for the specific arch among the list of assets
• latest_<gitforge>_tag : look for the latest tag (by sorting tags and finding the "largest" version). Then using the corresponding tar.gz url. Tags containing rc, beta, alpha, start are ignored, and actually any tag which doesn't look like x.y.z or vx.y.z
• latest_<gitforge>_commit : will use the latest commit on github, and the corresponding tarball. If this is used for the 'main' source, it will also assume that the version is YYYY.MM.DD corresponding to the date of the commit.

It is also possible to define autoupdate.upstream to use a different Git repository instead of the code repository from the upstream section of the manifest. This can be useful when, for example, the app uses other assets such as plugin from a different repository.

If the upstream project provides non-standard tag or release names, you can fix this, with a regex with a matching group.

For example, if tags look like release-v4.1, put:

autoupdate.version_regex = "^release-v(.*)$"

And the autoupdater will use the matched group (here: 4.1) as the version.

You can make sure that your autoupdate strategy is working well immediately (without waiting for the next check on the infra) by doing the following:

1. Clone this repo: https://github.com/YunoHost/apps_tools

2. In apps_tools open a terminal to run the following commands:

   # Create test branch
   git checkout -b localtest
   
   # Create a Python virtual environment
   python -m venv venv
   source venv/bin/activate
   
   # Install dependencies (if you don't have pip already installed on your system, check https://pip.pypa.io/en/stable/installation)
   pip install -r requirements.txt
   
   # Run autoupdate script - replace '/path/to/myapp_ynh' with your actual local app path
   ./autoupdate_app_sources/autoupdate_app_sources.py '/path/to/myapp_ynh'

3. If the return output includes:
   • Apps udpated, it ran successfully. Note that it will automatically make local changes in your app's manifest.toml (which can be discarded as they will be made automatically later online by the YNH infra);
   • Apps failed, the autoupdate stragegy is not working properly - check the debug info;
   • none of the above but apps -> Autoupdater just ran, here are the results:, it ran successfully but the app was already up to date.

Provision/Update

• For elements with prefetch = true, will download the asset (for the appropriate architecture) and store them in /var/cache/yunohost/download/$app/$source_id, to be later picked up by ynh_setup_source. (NB: this only happens during install and upgrade, not restore)

Deprovision

• Nothing (just cleanup the cache)

System User

Provision a system user to be used by the app. The username is exactly equal to the app id

Example

[resources.system_user]
# (empty - defaults are usually okay)

Properties

• allow_ssh: (default: False) Adds the user to the ssh.app group, allowing SSH connection via this user
• allow_sftp: (default: False) Adds the user to the sftp.app group, allowing SFTP connection via this user
• allow_email: (default: False) Enable authentication on the mail stack for the system user and send mail using __APP__@__DOMAIN__. A mail_pwd setting is automatically defined (similar to db_pwd for databases). You can then configure the app to use __APP__ and __MAIL_PWD__ as SMTP credentials (with host 127.0.0.1). You can also tweak the user-part of the domain-part of the email used by manually defining a custom setting mail_user or mail_domain
• home: (default: /var/www/__APP__) Defines the home property for this user. NB: unfortunately you can't simply use __INSTALL_DIR__ or __DATA_DIR__ for now

Provision/Update

• will create the system user if it doesn't exists yet
• will add/remove the ssh/sftp.app groups

Deprovision

• deletes the user and group