diff --git a/pages/06.contribute/10.packaging_apps/80.resources/11.helpers/packaging_apps_helpers.md b/pages/06.contribute/10.packaging_apps/80.resources/11.helpers/packaging_apps_helpers.md
index 9f759b4d..819ada1a 100644
--- a/pages/06.contribute/10.packaging_apps/80.resources/11.helpers/packaging_apps_helpers.md
+++ b/pages/06.contribute/10.packaging_apps/80.resources/11.helpers/packaging_apps_helpers.md
@@ -7,280 +7,290 @@ routes:
default: '/packaging_apps_helpers'
---
-Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/doc/generate_helper_doc.py) on 01/03/2024 (YunoHost version 11.2.10.3)
+Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/doc/generate_helper_doc.py) on 11/04/2024 (YunoHost version 11.2.11.1)
+
## APPS
-#### ynh_install_apps
-
+### ynh_install_apps
[details summary="Install others YunoHost apps" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_install_apps --apps="appfoo?domain=domain.foo&path=/foo appbar?domain=domain.bar&path=/bar&admin=USER&language=fr&is_public=1&pass?word=pass&port=666"`
**Arguments**:
-
- `-a`, `--apps=`: apps to install
-**Details**:
+**Details**:
Requires YunoHost version *.*.* or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apps#L9)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apps#L9)
[/details]
-----------------
-#### ynh_remove_apps
+---
+### ynh_remove_apps
[details summary="Remove other YunoHost apps" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_apps`
-**Details**:
+**Details**:
Other YunoHost apps will be removed only if no other apps need them.
Requires YunoHost version *.*.* or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apps#L65)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apps#L65)
[/details]
-----------------
-#### ynh_spawn_app_shell
+---
+### ynh_spawn_app_shell
[details summary="Spawn a Bash shell with the app environment loaded" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_spawn_app_shell --app="app"
| arg: -a, --app= - the app ID`
**Examples**:
+
+
+- ` ynh_spawn_app_shell --app="APP" <<< 'echo "$USER"'`
+
+
+
+- ` ynh_spawn_app_shell --app="APP" < /tmp/some_script.bash`
+
+
-- `ynh_spawn_app_shell --app="APP" <<< 'echo "$USER"'`
-
-- `ynh_spawn_app_shell --app="APP" < /tmp/some_script.bash`
-
-**Details**:
+**Details**:
Requires YunoHost version 11.0.* or higher, and that the app relies on packaging v2 or higher.
The spawned shell will have environment variables loaded and environment files sourced
from the app's service configuration file (defaults to $app.service, overridable by the packager with `service` setting).
If the app relies on a specific PHP version, then `php` will be aliased that version. The PHP command will also be appended with the `phpflags` settings.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apps#L128)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apps#L128)
[/details]
-----------------
+
+---
+
## APT
-#### ynh_package_is_installed
-
+### ynh_package_is_installed
[details summary="Check either a package is installed or not" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_package_is_installed --package=name`
**Arguments**:
-
- `-p`, `--package=`: the package name to check
**Returns**: 0 if the package is installed, 1 else.
**Example**: `ynh_package_is_installed --package=yunohost && echo "installed"`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L53)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L53)
[/details]
-----------------
-#### ynh_package_version
+---
+### ynh_package_version
[details summary="Get the version of an installed package" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_package_version --package=name`
**Arguments**:
-
- `-p`, `--package=`: the package name to get version
**Returns**: the version or an empty string
**Example**: `version=$(ynh_package_version --package=yunohost)`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L75)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L74)
[/details]
-----------------
-#### ynh_package_update
+---
+### ynh_package_update
[details summary="Update package index files" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_package_update`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L107)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L106)
[/details]
-----------------
-#### ynh_package_install
+---
+### ynh_package_install
[details summary="Install package(s)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_package_install name [name [...]]`
**Arguments**:
-
- `name`: the package name to install
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L117)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L116)
[/details]
-----------------
-#### ynh_package_remove
+---
+### ynh_package_remove
[details summary="Remove package(s)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_package_remove name [name [...]]`
**Arguments**:
-
- `name`: the package name to remove
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L128)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L127)
[/details]
-----------------
-#### ynh_package_autoremove
+---
+### ynh_package_autoremove
[details summary="Remove package(s) and their uneeded dependencies" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_package_autoremove name [name [...]]`
**Arguments**:
-
- `name`: the package name to remove
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L138)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L137)
[/details]
-----------------
-#### ynh_package_autopurge
+---
+### ynh_package_autopurge
[details summary="Purge package(s) and their uneeded dependencies" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_package_autopurge name [name [...]]`
**Arguments**:
-
- `name`: the package name to autoremove and purge
-**Details**:
+**Details**:
Requires YunoHost version 2.7.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L148)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L147)
[/details]
-----------------
-#### ynh_install_app_dependencies
+---
+### ynh_install_app_dependencies
[details summary="Define and install dependencies with a equivs control file" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_install_app_dependencies dep [dep [...]]`
**Arguments**:
-
- `dep`: the package name to install in dependence.
- `"dep1|dep2|…"`: You can specify alternatives. It will require to install (dep1 or dep2, etc).
-**Details**:
+**Details**:
This helper can/should only be called once per app
example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L225)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L224)
[/details]
-----------------
-#### ynh_add_app_dependencies
+---
+### ynh_add_app_dependencies
[details summary="Add dependencies to install with ynh_install_app_dependencies" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_add_app_dependencies --package=phpversion [--replace]`
**Arguments**:
-
- `-p`, `--package=`: Packages to add as dependencies for the app.
-**Details**:
+**Details**:
Requires YunoHost version 3.8.1 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L338)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L337)
[/details]
-----------------
-#### ynh_remove_app_dependencies
+---
+### ynh_remove_app_dependencies
[details summary="Remove fake package and its dependencies" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_app_dependencies`
-**Details**:
+**Details**:
Dependencies will removed only if no other package need them.
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L357)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L356)
[/details]
-----------------
-#### ynh_install_extra_app_dependencies
+---
+### ynh_install_extra_app_dependencies
[details summary="Install packages from an extra repository properly." class="helper-card-subtitle text-muted"]
**Usage**: `ynh_install_extra_app_dependencies --repo="repo" --package="dep1 dep2" [--key=key_url] [--name=name]`
**Arguments**:
-
- `-r`, `--repo=`: Complete url of the extra repository.
- `-p`, `--package=`: The packages to install from this extra repository
- `-k`, `--key=`: url to get the public key.
- `-n`, `--name=`: Name for the files for this repo, $app as default value.
-**Details**:
+**Details**:
Requires YunoHost version 3.8.1 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/apt#L391)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/apt#L390)
[/details]
-----------------
+
+---
+
## BACKUP
-#### ynh_backup
-
+### ynh_backup
[details summary="Add a file or a directory to the list of paths to backup" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_backup --src_path=src_path [--dest_path=dest_path] [--is_big] [--not_mandatory]`
**Arguments**:
-
- `-s`, `--src_path=`: file or directory to bind or symlink or copy. it shouldn't be in the backup dir.
- `-d`, `--dest_path=`: destination file or directory inside the backup dir
- `-b`, `--is_big`: Indicate data are big (mail, video, image ...)
- `-m`, `--not_mandatory`: Indicate that if the file is missing, the backup can ignore it.
-**Details**:
+**Details**:
This helper can be used both in a system backup hook, and in an app backup script
`ynh_backup` writes `src_path` and the relative `dest_path` into a CSV file, and it
@@ -289,7 +299,6 @@ creates the parent destination directory
If `dest_path` is ended by a slash it complete this path with the basename of `src_path`.
Example in the context of a wordpress app :
-
```
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"
# => This line will be added into CSV file
@@ -334,44 +343,52 @@ all backups for this app until the setting is removed.
Requires YunoHost version 2.4.0 or higher.
Requires YunoHost version 3.5.0 or higher for the argument `--not_mandatory`
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L64)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L64)
[/details]
-----------------
-#### ynh_restore
+---
+### ynh_restore
[details summary="Restore all files that were previously backuped in a core backup script or app backup script" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_restore`
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L179)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L179)
[/details]
-----------------
-#### ynh_restore_file
+---
+### ynh_restore_file
[details summary="Restore a file or a directory" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_restore_file --origin_path=origin_path [--dest_path=dest_path] [--not_mandatory]`
**Arguments**:
-
- `-o`, `--origin_path=`: Path where was located the file or the directory before to be backuped or relative path to $YNH_CWD where it is located in the backup archive
- `-d`, `--dest_path=`: Path where restore the file or the dir. If unspecified, the destination will be `ORIGIN_PATH` or if the `ORIGIN_PATH` doesn't exist in the archive, the destination will be searched into `backup.csv`
- `-m`, `--not_mandatory`: Indicate that if the file is missing, the restore process can ignore it.
**Examples**:
-
-- `ynh_restore_file -o "/etc/nginx/conf.d/$domain.d/$app.conf"`
-
+
+
+- ` ynh_restore_file -o "/etc/nginx/conf.d/$domain.d/$app.conf"`
+
+
+
- `You can also use relative paths:`
+
+
+
+- ` ynh_restore_file -o "conf/nginx.conf"`
+
+
-- `ynh_restore_file -o "conf/nginx.conf"`
-
-**Details**:
+**Details**:
Use the registered path in backup_list by ynh_backup to restore the file at the right place.
If `DEST_PATH` already exists and is lighter than 500 Mo, a backup will be made in
@@ -385,79 +402,79 @@ if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into
Requires YunoHost version 2.6.4 or higher.
Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L238)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L238)
[/details]
-----------------
-#### ynh_store_file_checksum
+---
+### ynh_store_file_checksum
[details summary="Calculate and store a file checksum into the app settings" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_store_file_checksum --file=file`
**Arguments**:
-
- `-f`, `--file=`: The file on which the checksum will performed, then stored.
-**Details**:
+**Details**:
$app should be defined when calling this helper
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L306)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L306)
[/details]
-----------------
-#### ynh_backup_if_checksum_is_different
+---
+### ynh_backup_if_checksum_is_different
[details summary="Verify the checksum and backup the file if it's different" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_backup_if_checksum_is_different --file=file`
**Arguments**:
-
- `-f`, `--file=`: The file on which the checksum test will be perfomed.
**Returns**: the name of a backup file, or nothing
-**Details**:
+**Details**:
This helper is primarily meant to allow to easily backup personalised/manually
modified config files.
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L357)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L357)
[/details]
-----------------
-#### ynh_delete_file_checksum
+---
+### ynh_delete_file_checksum
[details summary="Delete a file checksum from the app settings" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_delete_file_checksum --file=file`
**Arguments**:
-
- `-f`, `--file=`: The file for which the checksum will be deleted
-**Details**:
+**Details**:
$app should be defined when calling this helper
Requires YunoHost version 3.3.1 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L397)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L397)
[/details]
-----------------
-#### ynh_backup_before_upgrade
+---
+### ynh_backup_before_upgrade
[details summary="Make a backup in case of failed upgrade" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_backup_before_upgrade`
-**Details**:
+**Details**:
Usage in a package script:
-
```
ynh_backup_before_upgrade
ynh_clean_setup () {
@@ -468,19 +485,19 @@ Usage in a package script:
Requires YunoHost version 2.7.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L432)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L432)
[/details]
-----------------
-#### ynh_restore_upgradebackup
+---
+### ynh_restore_upgradebackup
[details summary="Restore a previous backup if the upgrade process failed" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_restore_upgradebackup`
-**Details**:
+**Details**:
Usage in a package script:
-
```
ynh_backup_before_upgrade
ynh_clean_setup () {
@@ -491,30 +508,32 @@ Usage in a package script:
Requires YunoHost version 2.7.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/backup#L480)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/backup#L480)
[/details]
-----------------
+
+---
+
## CONFIG
+
## FAIL2BAN
-#### ynh_add_fail2ban_config
-
+### ynh_add_fail2ban_config
[details summary="Create a dedicated fail2ban config (jail and filter conf files)" class="helper-card-subtitle text-muted"]
**Usage**: `1: ynh_add_fail2ban_config --logpath=log_file --failregex=filter [--max_retry=max_retry] [--ports=ports]
2: ynh_add_fail2ban_config --use_template`
**Arguments**:
-
- `-l`, `--logpath=`: Log file to be checked by fail2ban
- `-r`, `--failregex=`: Failregex to be looked for by fail2ban
- `-m`, `--max_retry=`: Maximum number of retries allowed before banning IP address - default: 3
- `-p`, `--ports=`: Ports blocked for a banned IP address - default: http,https
- `-t`, `--use_template`: Use this helper in template mode
-**Details**:
+**Details**:
-----------------------------------------------------------------------------
This will use a template in `../conf/f2b_jail.conf` and `../conf/f2b_filter.conf`
@@ -522,7 +541,6 @@ See the documentation of `ynh_add_config` for a description of the template
format and how placeholders are replaced with actual variables.
Generally your template will look like that by example (for synapse):
-
```
f2b_jail.conf:
[__APP__]
@@ -532,7 +550,6 @@ f2b_jail.conf:
logpath = /var/log/__APP__/logfile.log
maxretry = 3
```
-
```
f2b_filter.conf:
[INCLUDES]
@@ -557,45 +574,47 @@ matched by a group named "`host`". The tag "``" can be used for standard
IP/hostname matching and is only an alias for `(?:::f{4,6}:)?(?P[\w\-.^_]+)`
You can find some more explainations about how to make a regex here :
-
+https://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Filters
To validate your regex you can test with this command:
-
```
fail2ban-regex /var/log/YOUR_LOG_FILE_PATH /etc/fail2ban/filter.d/YOUR_APP.conf
```
Requires YunoHost version 4.1.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/fail2ban#L62)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/fail2ban#L62)
[/details]
-----------------
-#### ynh_remove_fail2ban_config
+---
+### ynh_remove_fail2ban_config
[details summary="Remove the dedicated fail2ban config (jail and filter conf files)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_fail2ban_config`
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/fail2ban#L134)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/fail2ban#L134)
[/details]
-----------------
+
+---
+
## GETOPTS
+
## HARDWARE
-#### ynh_get_ram
-
+### ynh_get_ram
[details summary="Get the total or free amount of RAM+swap on the system" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_get_ram [--free|--total] [--ignore_swap|--only_swap]`
**Arguments**:
-
- `-f`, `--free`: Count free RAM+swap
- `-t`, `--total`: Count total RAM+swap
- `-s`, `--ignore_swap`: Ignore swap, consider only real RAM
@@ -603,21 +622,21 @@ Requires YunoHost version 3.5.0 or higher.
**Returns**: the amount of free ram, in MB (MegaBytes)
-**Details**:
+**Details**:
Requires YunoHost version 3.8.1 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/hardware#L13)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/hardware#L13)
[/details]
-----------------
-#### ynh_require_ram
+---
+### ynh_require_ram
[details summary="Return 0 or 1 depending if the system has a given amount of RAM+swap free or total" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_require_ram --required=RAM [--free|--total] [--ignore_swap|--only_swap]`
**Arguments**:
-
- `-r`, `--required=`: The amount to require, in MB
- `-f`, `--free`: Count free RAM+swap
- `-t`, `--total`: Count total RAM+swap
@@ -626,564 +645,578 @@ Requires YunoHost version 3.8.1 or higher.
**Returns**: 1 if the ram is under the requirement, 0 otherwise.
-**Details**:
+**Details**:
Requires YunoHost version 3.8.1 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/hardware#L75)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/hardware#L75)
[/details]
-----------------
+
+---
+
## LOGGING
-#### ynh_die
-
+### ynh_die
[details summary="Print a message to stderr and exit" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_die --message=MSG [--ret_code=RETCODE]`
**Arguments**:
-
- `-m`, `--message=`: Message to display
- `-c`, `--ret_code=`: Exit code to exit with
-**Details**:
+**Details**:
Requires YunoHost version 2.4.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L10)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L10)
[/details]
-----------------
-#### ynh_print_info
+---
+### ynh_print_info
[details summary="Display a message in the 'INFO' logging category" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_print_info --message="Some message"`
**Arguments**:
-
- `-m`, `--message=`: Message to display
-**Details**:
+**Details**:
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L30)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L30)
[/details]
-----------------
-#### ynh_print_warn
+---
+### ynh_print_warn
[details summary="Print a warning on stderr" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_print_warn --message="Text to print"`
**Arguments**:
-
- `-m`, `--message=`: The text to print
-**Details**:
+**Details**:
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L56)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L56)
[/details]
-----------------
-#### ynh_print_err
+---
+### ynh_print_err
[details summary="Print an error on stderr" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_print_err --message="Text to print"`
**Arguments**:
-
- `-m`, `--message=`: The text to print
-**Details**:
+**Details**:
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L73)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L73)
[/details]
-----------------
-#### ynh_exec_err
+---
+### ynh_exec_err
[details summary="Execute a command and print the result as an error" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_exec_err your command and args`
**Arguments**:
-
- `command`: command to execute
-**Details**:
+**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_err
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L92)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L92)
[/details]
-----------------
-#### ynh_exec_warn
+---
+### ynh_exec_warn
[details summary="Execute a command and print the result as a warning" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_exec_warn your command and args`
**Arguments**:
-
- `command`: command to execute
-**Details**:
+**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L113)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L113)
[/details]
-----------------
-#### ynh_exec_warn_less
+---
+### ynh_exec_warn_less
[details summary="Execute a command and force the result to be printed on stdout" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_exec_warn_less your command and args`
**Arguments**:
-
- `command`: command to execute
-**Details**:
+**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L134)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L134)
[/details]
-----------------
-#### ynh_exec_quiet
+---
+### ynh_exec_quiet
[details summary="Execute a command and redirect stdout in /dev/null" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_exec_quiet your command and args`
**Arguments**:
-
- `command`: command to execute
-**Details**:
+**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L155)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L155)
[/details]
-----------------
-#### ynh_exec_fully_quiet
+---
+### ynh_exec_fully_quiet
[details summary="Execute a command and redirect stdout and stderr in /dev/null" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_exec_quiet your command and args`
**Arguments**:
-
- `command`: command to execute
-**Details**:
+**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_quiet
Requires YunoHost version 3.2.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L176)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L176)
[/details]
-----------------
-#### ynh_exec_and_print_stderr_only_if_error
+---
+### ynh_exec_and_print_stderr_only_if_error
[details summary="Execute a command and redirect stderr in /dev/null. Print stderr on error." class="helper-card-subtitle text-muted"]
**Usage**: `ynh_exec_and_print_stderr_only_if_error your command and args`
**Arguments**:
-
- `command`: command to execute
-**Details**:
+**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_and_print_stderr_only_if_error
Requires YunoHost version 11.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L197)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L197)
[/details]
-----------------
-#### ynh_script_progression
+---
+### ynh_script_progression
[details summary="Print a progress bar showing the progression of an app script" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_script_progression --message=message [--weight=weight] [--time]`
**Arguments**:
-
- `-m`, `--message=`: The text to print
- `-w`, `--weight=`: The weight for this progression. This value is 1 by default. Use a bigger value for a longer part of the script.
- `-t`, `--time`: Print the execution time since the last call to this helper. Especially usefull to define weights. The execution time is given for the duration since the previous call. So the weight should be applied to this previous call.
- `-l`, `--last`: Use for the last call of the helper, to fill the progression bar.
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L257)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L257)
[/details]
-----------------
-#### ynh_return
+---
+### ynh_return
[details summary="Return data to the YunoHost core for later processing
(to be used by special hooks like app config panel and core diagnosis)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_return somedata`
-**Details**:
+**Details**:
Requires YunoHost version 3.6.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logging#L345)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logging#L345)
[/details]
-----------------
+
+---
+
## LOGROTATE
-#### ynh_use_logrotate
-
+### ynh_use_logrotate
[details summary="Use logrotate to manage the logfile" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_use_logrotate [--logfile=/log/file] [--specific_user=user/group]`
**Arguments**:
-
- `-l`, `--logfile=`: absolute path of logfile
- `-u`, `--specific_user=`: run logrotate as the specified user and group. If not specified logrotate is runned as root.
-**Details**:
+**Details**:
If no `--logfile` is provided, `/var/log/$app` will be used as default.
`logfile` can point to a directory or a file.
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logrotate#L15)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logrotate#L15)
[/details]
-----------------
-#### ynh_remove_logrotate
+---
+### ynh_remove_logrotate
[details summary="Remove the app's logrotate config." class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_logrotate`
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/logrotate#L99)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/logrotate#L99)
[/details]
-----------------
+
+---
+
## MULTIMEDIA
-#### ynh_multimedia_build_main_dir
-
+### ynh_multimedia_build_main_dir
[details summary="Initialize the multimedia directory system" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_multimedia_build_main_dir`
-**Details**:
+**Details**:
Requires YunoHost version 4.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/multimedia#L11)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/multimedia#L11)
[/details]
-----------------
-#### ynh_multimedia_addfolder
+---
-[details summary="Add a directory in YunoHost.multimedia" class="helper-card-subtitle text-muted"]
+### ynh_multimedia_addfolder
+[details summary="Add a directory in yunohost.multimedia" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_multimedia_addfolder --source_dir="source_dir" --dest_dir="dest_dir"`
**Arguments**:
-
- `-s`, `--source_dir=`: Source directory - The real directory which contains your medias.
-- `-d`, `--dest_dir=`: Destination directory - The name and the place of the symbolic link, relative to "/home/YunoHost.multimedia"
+- `-d`, `--dest_dir=`: Destination directory - The name and the place of the symbolic link, relative to "/home/yunohost.multimedia"
-**Details**:
+**Details**:
This "directory" will be a symbolic link to a existing directory.
Requires YunoHost version 4.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/multimedia#L64)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/multimedia#L64)
[/details]
-----------------
-#### ynh_multimedia_addaccess
+---
+### ynh_multimedia_addaccess
[details summary="Allow an user to have an write authorisation in multimedia directories" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_multimedia_addaccess user_name`
**Arguments**:
-
- `-u`, `--user_name=`: The name of the user which gain this access.
-**Details**:
+**Details**:
Requires YunoHost version 4.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/multimedia#L93)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/multimedia#L93)
[/details]
-----------------
+
+---
+
## MYSQL
-#### ynh_mysql_connect_as
-
+### ynh_mysql_connect_as
[details summary="Open a connection as a user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_mysql_connect_as --user=user --password=password [--database=database]`
**Arguments**:
-
- `-u`, `--user=`: the user name to connect as
- `-p`, `--password=`: the user password
- `-d`, `--database=`: the database to connect to
**Examples**:
+
+
+- ` ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"`
+
+
+
+- ` ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql`
+
+
-- `ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"`
-
-- `ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql`
-
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/mysql#L15)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/mysql#L15)
[/details]
-----------------
-#### ynh_mysql_execute_as_root
+---
+### ynh_mysql_execute_as_root
[details summary="Execute a command as root user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_mysql_execute_as_root --sql=sql [--database=database]`
**Arguments**:
-
- `-s`, `--sql=`: the SQL command to execute
- `-d`, `--database=`: the database to connect to
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/mysql#L36)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/mysql#L36)
[/details]
-----------------
-#### ynh_mysql_execute_file_as_root
+---
+### ynh_mysql_execute_file_as_root
[details summary="Execute a command from a file as root user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_mysql_execute_file_as_root --file=file [--database=database]`
**Arguments**:
-
- `-f`, `--file=`: the file containing SQL commands
- `-d`, `--database=`: the database to connect to
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/mysql#L60)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/mysql#L60)
[/details]
-----------------
-#### ynh_mysql_dump_db
+---
+### ynh_mysql_dump_db
[details summary="Dump a database" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_mysql_dump_db --database=database`
**Arguments**:
-
- `-d`, `--database=`: the database name to dump
**Returns**: The mysqldump output
**Example**: `ynh_mysql_dump_db --database=roundcube > ./dump.sql`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/mysql#L128)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/mysql#L128)
[/details]
-----------------
-#### ynh_mysql_user_exists
+---
+### ynh_mysql_user_exists
[details summary="Check if a mysql user exists" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_mysql_user_exists --user=user`
**Arguments**:
-
- `-u`, `--user=`: the user for which to check existence
**Returns**: 0 if the user exists, 1 otherwise.
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/mysql#L160)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/mysql#L160)
[/details]
-----------------
-#### ynh_mysql_setup_db
+---
+### ynh_mysql_setup_db
[details summary="Create a database, an user and its password. Then store the password in the app's config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_mysql_setup_db --db_user=user --db_name=name [--db_pwd=pwd]`
**Arguments**:
-
- `-u`, `--db_user=`: Owner of the database
- `-n`, `--db_name=`: Name of the database
- `-p`, `--db_pwd=`: Password of the database. If not provided, a password will be generated
-**Details**:
+**Details**:
After executing this helper, the password of the created database will be available in `$db_pwd`
It will also be stored as "`mysqlpwd`" into the app settings.
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/mysql#L198)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/mysql#L198)
[/details]
-----------------
-#### ynh_mysql_remove_db
+---
+### ynh_mysql_remove_db
[details summary="Remove a database if it exists, and the associated user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_mysql_remove_db --db_user=user --db_name=name`
**Arguments**:
-
- `-u`, `--db_user=`: Owner of the database
- `-n`, `--db_name=`: Name of the database
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/mysql#L224)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/mysql#L224)
[/details]
-----------------
+
+---
+
## NETWORK
-#### ynh_find_port
-
+### ynh_find_port
[details summary="Find a free port and return it" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_find_port --port=begin_port`
**Arguments**:
-
- `-p`, `--port=`: port to start to search
**Returns**: the port number
**Example**: `port=$(ynh_find_port --port=8080)`
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/network#L12)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/network#L12)
[/details]
-----------------
-#### ynh_port_available
+---
+### ynh_port_available
[details summary="Test if a port is available" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_find_port --port=XYZ`
**Arguments**:
-
- `-p`, `--port=`: port to check
**Returns**: 0 if the port is available, 1 if it is already used by another process.
**Example**: `ynh_port_available --port=1234 || ynh_die --message="Port 1234 is needs to be available for this app"`
-**Details**:
+**Details**:
Requires YunoHost version 3.8.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/network#L36)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/network#L36)
[/details]
-----------------
-#### ynh_validate_ip4
+---
+### ynh_validate_ip4
[details summary="Validate an IPv4 address" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_validate_ip4 --ip_address=ip_address`
**Arguments**:
-
- `-i`, `--ip_address=`: the ipv4 address to check
**Returns**: 0 for valid ipv4 addresses, 1 otherwise
**Example**: `ynh_validate_ip4 111.222.333.444`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/network#L99)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/network#L99)
[/details]
-----------------
-#### ynh_validate_ip6
+---
+### ynh_validate_ip6
[details summary="Validate an IPv6 address" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_validate_ip6 --ip_address=ip_address`
**Arguments**:
-
- `-i`, `--ip_address=`: the ipv6 address to check
**Returns**: 0 for valid ipv6 addresses, 1 otherwise
**Example**: `ynh_validate_ip6 2000:dead:beef::1`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/network#L119)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/network#L119)
[/details]
-----------------
+
+---
+
## NGINX
-#### ynh_add_nginx_config
-
+### ynh_add_nginx_config
[details summary="Create a dedicated nginx config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_add_nginx_config`
-**Details**:
+**Details**:
This will use a template in `../conf/nginx.conf`
See the documentation of `ynh_add_config` for a description of the template
format and how placeholders are replaced with actual variables.
Additionally, ynh_add_nginx_config will replace:
-
- `#sub_path_only` by empty string if `path_url` is not `'/'`
- `#root_path_only` by empty string if `path_url` *is* `'/'`
@@ -1192,45 +1225,49 @@ location
Requires YunoHost version 4.1.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/nginx#L19)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/nginx#L19)
[/details]
-----------------
-#### ynh_remove_nginx_config
+---
+### ynh_remove_nginx_config
[details summary="Remove the dedicated nginx config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_nginx_config`
-**Details**:
+**Details**:
Requires YunoHost version 2.7.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/nginx#L41)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/nginx#L41)
[/details]
-----------------
-#### ynh_change_url_nginx_config
+---
+### ynh_change_url_nginx_config
[details summary="Regen the nginx config in a change url context" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_change_url_nginx_config`
-**Details**:
+**Details**:
Requires YunoHost version 11.1.9 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/nginx#L52)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/nginx#L52)
[/details]
-----------------
+
+---
+
## NODEJS
-#### ynh_use_nodejs
-
+### ynh_use_nodejs
[details summary="Load the version of node for an app, and set variables." class="helper-card-subtitle text-muted"]
**Usage**: `ynh_use_nodejs`
-**Details**:
+**Details**:
`ynh_use_nodejs` has to be used in any app scripts before using node for the first time.
This helper will provide alias and variables to use in your scripts.
@@ -1252,44 +1289,39 @@ Exemple: $ynh_node_load_PATH $final_path/script_that_use_npm.sh`
Finally, to start a nodejs service with the correct version, 2 solutions
Either the app is dependent of node or npm, but does not called it directly.
In such situation, you need to load PATH :
-
```
Environment="__NODE_ENV_PATH__"
ExecStart=__FINALPATH__/my_app
```
-
-You will replace **NODE_ENV_PATH** with $ynh_node_load_PATH.
+You will replace __NODE_ENV_PATH__ with $ynh_node_load_PATH.
Or node start the app directly, then you don't need to load the PATH variable
-
```
ExecStart=__YNH_NODE__ my_app run
```
-
-You will replace **YNH_NODE** with $ynh_node
+You will replace __YNH_NODE__ with $ynh_node
2 other variables are also available
-
-- $nodejs_path: The absolute path to node binaries for the chosen version.
-- $nodejs_version: Just the version number of node for this app. Stored as 'nodejs_version' in settings.yml.
+ - $nodejs_path: The absolute path to node binaries for the chosen version.
+ - $nodejs_version: Just the version number of node for this app. Stored as 'nodejs_version' in settings.yml.
Requires YunoHost version 2.7.12 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/nodejs#L52)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/nodejs#L52)
[/details]
-----------------
-#### ynh_install_nodejs
+---
+### ynh_install_nodejs
[details summary="Install a specific version of nodejs" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_install_nodejs --nodejs_version=nodejs_version`
**Arguments**:
-
- `-n`, `--nodejs_version=`: Version of node to install. When possible, your should prefer to use major version number (e.g. 8 instead of 8.10.0). The crontab will then handle the update of minor versions when needed.
-**Details**:
+**Details**:
ynh_install_nodejs will install the version of node provided as argument by using n.
`n` (Node version management) uses the `PATH` variable to store the path of the version of node it is going to use.
@@ -1299,32 +1331,34 @@ Refer to `ynh_use_nodejs` for more information about available commands and vari
Requires YunoHost version 2.7.12 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/nodejs#L92)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/nodejs#L92)
[/details]
-----------------
-#### ynh_remove_nodejs
+---
+### ynh_remove_nodejs
[details summary="Remove the version of node used by the app." class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_nodejs`
-**Details**:
+**Details**:
This helper will check if another app uses the same version of node.
-
- If not, this version of node will be removed.
- If no other app uses node, n will be also removed.
Requires YunoHost version 2.7.12 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/nodejs#L165)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/nodejs#L165)
[/details]
-----------------
+
+---
+
## PERMISSION
-#### ynh_permission_create
-
+### ynh_permission_create
[details summary="Create a new permission for the app" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_permission_create --permission="permission" [--url="url"] [--additional_urls="second-url" [ "third-url" ]] [--auth_header=true|false]
@@ -1332,7 +1366,6 @@ Requires YunoHost version 2.7.12 or higher.
[--protected=true|false]`
**Arguments**:
-
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" already exist)
- `-u`, `--url=`: (optional) URL for which access will be allowed/forbidden. Note that if 'show_tile' is enabled, this URL will be the URL of the tile.
- `-A`, `--additional_urls=`: (optional) List of additional URL for which access will be allowed/forbidden
@@ -1342,12 +1375,11 @@ Requires YunoHost version 2.7.12 or higher.
- `-t`, `--show_tile=`: (optional) Define if a tile will be shown in the SSO. If yes the name of the tile will be the 'label' parameter. Defaults to false for the permission different than 'main'.
- `-P`, `--protected=`: (optional) 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'.
-**Details**:
+**Details**:
Example 1: `ynh_permission_create --permission=admin --url=/admin --additional_urls=domain.tld/admin /superadmin --allowed=alice bob \
--label="My app admin" --show_tile=true`
This example will create a new permission permission with this following effect:
-
- A tile named "My app admin" in the SSO will be available for the users alice and bob. This tile will point to the relative url '/admin'.
- Only the user alice and bob will have the access to theses following url: /admin, domain.tld/admin, /superadmin
@@ -1376,7 +1408,6 @@ For example:
re:domain.tld/app/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$
Note that globally the parameter 'url' and 'additional_urls' are same. The only difference is:
-
- 'url' is only one url, 'additional_urls' can be a list of urls. There are no limitation of 'additional_urls'
- 'url' is used for the url of tile in the SSO (if enabled with the 'show_tile' parameter)
@@ -1387,60 +1418,60 @@ The SSO pass (by default) to the application theses following HTTP header (linke
- "Email": user email
Generally this feature is usefull to authenticate automatically the user in the application but in some case the application don't work with theses header and theses header need to be disabled to have the application to work correctly.
-See for more informations
+See https://github.com/YunoHost/issues/issues/1420 for more informations
Requires YunoHost version 3.7.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L66)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L66)
[/details]
-----------------
-#### ynh_permission_delete
+---
+### ynh_permission_delete
[details summary="Remove a permission for the app (note that when the app is removed all permission is automatically removed)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_permission_delete --permission="permission"`
**Arguments**:
-
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
**Example**: `ynh_permission_delete --permission=editors`
-**Details**:
+**Details**:
Requires YunoHost version 3.7.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L152)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L152)
[/details]
-----------------
-#### ynh_permission_exists
+---
+### ynh_permission_exists
[details summary="Check if a permission exists" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_permission_exists --permission=permission
| exit: Return 1 if the permission doesn't exist, 0 otherwise`
**Arguments**:
-
- `-p`, `--permission=`: the permission to check
-**Details**:
+**Details**:
Requires YunoHost version 3.7.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L169)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L169)
[/details]
-----------------
-#### ynh_permission_url
+---
+### ynh_permission_url
[details summary="Redefine the url associated to a permission" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_permission_url --permission "permission" [--url="url"] [--add_url="new-url" [ "other-new-url" ]] [--remove_url="old-url" [ "other-old-url" ]]
[--auth_header=true|false] [--clear_urls]`
**Arguments**:
-
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
- `-u`, `--url=`: (optional) URL for which access will be allowed/forbidden. Note that if you want to remove url you can pass an empty sting as arguments ("").
- `-a`, `--add_url=`: (optional) List of additional url to add for which access will be allowed/forbidden.
@@ -1448,22 +1479,22 @@ Requires YunoHost version 3.7.0 or higher.
- `-h`, `--auth_header=`: (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application
- `-c`, `--clear_urls`: (optional) Clean all urls (url and additional_urls)
-**Details**:
+**Details**:
Requires YunoHost version 3.7.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L192)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L192)
[/details]
-----------------
-#### ynh_permission_update
+---
+### ynh_permission_update
[details summary="Update a permission for the app" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_permission_update --permission "permission" [--add="group" ["group" ...]] [--remove="group" ["group" ...]]
[--label="label"] [--show_tile=true|false] [--protected=true|false]`
**Arguments**:
-
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" already exist)
- `-a`, `--add=`: the list of group or users to enable add to the permission
- `-r`, `--remove=`: the list of group or users to remove from the permission
@@ -1471,69 +1502,71 @@ Requires YunoHost version 3.7.0 or higher.
- `-t`, `--show_tile=`: (optional) Define if a tile will be shown in the SSO
- `-P`, `--protected=`: (optional) 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.
-**Details**:
+**Details**:
Requires YunoHost version 3.7.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L260)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L260)
[/details]
-----------------
-#### ynh_permission_has_user
+---
+### ynh_permission_has_user
[details summary="Check if a permission has an user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_permission_has_user --permission=permission --user=user
| exit: Return 1 if the permission doesn't have that user or doesn't exist, 0 otherwise`
**Arguments**:
-
- `-p`, `--permission=`: the permission to check
- `-u`, `--user=`: the user seek in the permission
**Example**: `ynh_permission_has_user --permission=main --user=visitors`
-**Details**:
+**Details**:
Requires YunoHost version 3.7.1 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L329)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L329)
[/details]
-----------------
-#### ynh_legacy_permissions_exists
+---
+### ynh_legacy_permissions_exists
[details summary="Check if a legacy permissions exist" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_legacy_permissions_exists
| exit: Return 1 if the permission doesn't exist, 0 otherwise`
-**Details**:
+**Details**:
Requires YunoHost version 4.1.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L359)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L359)
[/details]
-----------------
-#### ynh_legacy_permissions_delete_all
+---
+### ynh_legacy_permissions_delete_all
[details summary="Remove all legacy permissions" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_legacy_permissions_delete_all`
**Example**: `if ynh_legacy_permissions_exists then ynh_legacy_permissions_delete_all # You can recreate the required permissions here with ynh_permission_create fi Requires YunoHost version 4.1.2 or higher.`
-
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/permission#L379)
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/permission#L379)
[/details]
-----------------
+
+---
+
## PHP
-#### ynh_add_fpm_config
-
+### ynh_add_fpm_config
[details summary="Create a dedicated PHP-FPM config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_add_fpm_config`
-**Details**:
+**Details**:
Case 1 (recommended) : your provided a snippet conf/extra_php-fpm.conf
The actual PHP configuration will be automatically generated,
@@ -1553,7 +1586,7 @@ Otherwise, if you want the user to have control over these, we encourage to crea
Case 2 (deprecate) : you provided an entire conf/php-fpm.conf
-The configuration will be hydrated, replacing **FOOBAR** placeholders with $foobar values, etc.
+The configuration will be hydrated, replacing __FOOBAR__ placeholders with $foobar values, etc.
The resulting configuration will be deployed to the appropriate place, /etc/php/$phpversion/fpm/pool.d/$app.conf
@@ -1593,330 +1626,339 @@ Set as 'high', the process manager will be set at 'static'. There will be always
Requires YunoHost version 4.1.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/php#L70)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/php#L70)
[/details]
-----------------
-#### ynh_remove_fpm_config
+---
+### ynh_remove_fpm_config
[details summary="Remove the dedicated PHP-FPM config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_fpm_config`
-**Details**:
+**Details**:
Requires YunoHost version 2.7.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/php#L284)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/php#L284)
[/details]
-----------------
-#### ynh_composer_exec
+---
+### ynh_composer_exec
[details summary="Execute a command with Composer" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_composer_exec [--phpversion=phpversion] [--workdir=$install_dir] --commands="commands"`
**Arguments**:
-
- `-v`, `--phpversion`: PHP version to use with composer
- `-w`, `--workdir`: The directory from where the command will be executed. Default $install_dir or $final_path
- `-c`, `--commands`: Commands to execute.
-**Details**:
+**Details**:
Requires YunoHost version 4.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/php#L517)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/php#L517)
[/details]
-----------------
-#### ynh_install_composer
+---
+### ynh_install_composer
[details summary="Install and initialize Composer in the given directory" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_install_composer [--phpversion=phpversion] [--workdir=$install_dir] [--install_args="--optimize-autoloader"] [--composerversion=composerversion]`
**Arguments**:
-
- `-v`, `--phpversion`: PHP version to use with composer
- `-w`, `--workdir`: The directory from where the command will be executed. Default $install_dir.
- `-a`, `--install_args`: Additional arguments provided to the composer install. Argument --no-dev already include
- `-c`, `--composerversion`: Composer version to install
-**Details**:
+**Details**:
Requires YunoHost version 4.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/php#L549)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/php#L549)
[/details]
-----------------
+
+---
+
## POSTGRESQL
-#### ynh_psql_connect_as
-
+### ynh_psql_connect_as
[details summary="Open a connection as a user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_connect_as --user=user --password=password [--database=database]`
**Arguments**:
-
- `-u`, `--user=`: the user name to connect as
- `-p`, `--password=`: the user password
- `-d`, `--database=`: the database to connect to
**Examples**:
+
+
+- ` ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"`
+
+
+
+- ` ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql`
+
+
-- `ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"`
-
-- `ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql`
-
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L18)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L18)
[/details]
-----------------
-#### ynh_psql_execute_as_root
+---
+### ynh_psql_execute_as_root
[details summary="Execute a command as root user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_execute_as_root --sql=sql [--database=database]`
**Arguments**:
-
- `-s`, `--sql=`: the SQL command to execute
- `-d`, `--database=`: the database to connect to
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L39)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L39)
[/details]
-----------------
-#### ynh_psql_execute_file_as_root
+---
+### ynh_psql_execute_file_as_root
[details summary="Execute a command from a file as root user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_execute_file_as_root --file=file [--database=database]`
**Arguments**:
-
- `-f`, `--file=`: the file containing SQL commands
- `-d`, `--database=`: the database to connect to
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L64)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L64)
[/details]
-----------------
-#### ynh_psql_dump_db
+---
+### ynh_psql_dump_db
[details summary="Dump a database" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_dump_db --database=database`
**Arguments**:
-
- `-d`, `--database=`: the database name to dump
**Returns**: the psqldump output
**Example**: `ynh_psql_dump_db 'roundcube' > ./dump.sql`
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L135)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L135)
[/details]
-----------------
-#### ynh_psql_user_exists
+---
+### ynh_psql_user_exists
[details summary="Check if a psql user exists" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_user_exists --user=user
| exit: Return 1 if the user doesn't exist, 0 otherwise`
**Arguments**:
-
- `-u`, `--user=`: the user for which to check existence
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L168)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L168)
[/details]
-----------------
-#### ynh_psql_database_exists
+---
+### ynh_psql_database_exists
[details summary="Check if a psql database exists" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_database_exists --database=database
| exit: Return 1 if the database doesn't exist, 0 otherwise`
**Arguments**:
-
- `-d`, `--database=`: the database for which to check existence
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L190)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L190)
[/details]
-----------------
-#### ynh_psql_setup_db
+---
+### ynh_psql_setup_db
[details summary="Create a database, an user and its password. Then store the password in the app's config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_setup_db --db_user=user --db_name=name [--db_pwd=pwd]`
**Arguments**:
-
- `-u`, `--db_user=`: Owner of the database
- `-n`, `--db_name=`: Name of the database
- `-p`, `--db_pwd=`: Password of the database. If not provided, a password will be generated
-**Details**:
+**Details**:
After executing this helper, the password of the created database will be available in $db_pwd
It will also be stored as "psqlpwd" into the app settings.
Requires YunoHost version 2.7.13 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L234)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L234)
[/details]
-----------------
-#### ynh_psql_remove_db
+---
+### ynh_psql_remove_db
[details summary="Remove a database if it exists, and the associated user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_psql_remove_db --db_user=user --db_name=name`
**Arguments**:
-
- `-u`, `--db_user=`: Owner of the database
- `-n`, `--db_name=`: Name of the database
-**Details**:
+**Details**:
Requires YunoHost version 2.7.13 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/postgresql#L265)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/postgresql#L265)
[/details]
-----------------
+
+---
+
## SETTING
-#### ynh_app_setting_get
-
+### ynh_app_setting_get
[details summary="Get an application setting" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_app_setting_get --app=app --key=key`
**Arguments**:
-
- `-a`, `--app=`: the application id
- `-k`, `--key=`: the setting to get
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/setting#L10)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/setting#L10)
[/details]
-----------------
-#### ynh_app_setting_set
+---
+### ynh_app_setting_set
[details summary="Set an application setting" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_app_setting_set --app=app --key=key --value=value`
**Arguments**:
-
- `-a`, `--app=`: the application id
- `-k`, `--key=`: the setting name to set
- `-v`, `--value=`: the setting value to set
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/setting#L36)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/setting#L36)
[/details]
-----------------
-#### ynh_app_setting_delete
+---
+### ynh_app_setting_delete
[details summary="Delete an application setting" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_app_setting_delete --app=app --key=key`
**Arguments**:
-
- `-a`, `--app=`: the application id
- `-k`, `--key=`: the setting to delete
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/setting#L62)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/setting#L62)
[/details]
-----------------
-#### ynh_webpath_available
+---
+### ynh_webpath_available
[details summary="Check availability of a web path" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_webpath_available --domain=domain --path_url=path`
**Arguments**:
-
- `-d`, `--domain=`: the domain/host of the url
- `-p`, `--path_url=`: the web path to check the availability of
**Example**: `ynh_webpath_available --domain=some.domain.tld --path_url=/coffee`
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/setting#L123)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/setting#L123)
[/details]
-----------------
-#### ynh_webpath_register
+---
+### ynh_webpath_register
[details summary="Register/book a web path for an app" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_webpath_register --app=app --domain=domain --path_url=path`
**Arguments**:
-
- `-a`, `--app=`: the app for which the domain should be registered
- `-d`, `--domain=`: the domain/host of the web path
- `-p`, `--path_url=`: the web path to be registered
**Example**: `ynh_webpath_register --app=wordpress --domain=some.domain.tld --path_url=/coffee`
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/setting#L145)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/setting#L145)
[/details]
-----------------
+
+---
+
## STRING
-#### ynh_string_random
-
+### ynh_string_random
[details summary="Generate a random string" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_string_random [--length=string_length]`
**Arguments**:
-
- `-l`, `--length=`: the string length to generate (default: 24)
- `-f`, `--filter=`: the kind of characters accepted in the output (default: 'A-Za-z0-9')
@@ -1924,94 +1966,95 @@ Requires YunoHost version 2.6.4 or higher.
**Example**: `pwd=$(ynh_string_random --length=8)`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/string#L13)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/string#L13)
[/details]
-----------------
-#### ynh_replace_string
+---
+### ynh_replace_string
[details summary="Substitute/replace a string (or expression) by another in a file" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_replace_string --match_string=match_string --replace_string=replace_string --target_file=target_file`
**Arguments**:
-
- `-m`, `--match_string=`: String to be searched and replaced in the file
- `-r`, `--replace_string=`: String that will replace matches
- `-f`, `--target_file=`: File in which the string will be replaced.
-**Details**:
+**Details**:
As this helper is based on sed command, regular expressions and references to
sub-expressions can be used (see sed manual page for more information)
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/string#L40)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/string#L40)
[/details]
-----------------
-#### ynh_replace_special_string
+---
+### ynh_replace_special_string
[details summary="Substitute/replace a special string by another in a file" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_replace_special_string --match_string=match_string --replace_string=replace_string --target_file=target_file`
**Arguments**:
-
- `-m`, `--match_string=`: String to be searched and replaced in the file
- `-r`, `--replace_string=`: String that will replace matches
- `-t`, `--target_file=`: File in which the string will be replaced.
-**Details**:
+**Details**:
This helper will use ynh_replace_string, but as you can use special
characters, you can't use some regular expressions and sub-expressions.
Requires YunoHost version 2.7.7 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/string#L71)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/string#L71)
[/details]
-----------------
-#### ynh_sanitize_dbid
+---
+### ynh_sanitize_dbid
[details summary="Sanitize a string intended to be the name of a database" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_sanitize_dbid --db_name=name`
**Arguments**:
-
- `-n`, `--db_name=`: name to correct/sanitize
**Returns**: the corrected name
**Example**: `dbname=$(ynh_sanitize_dbid $app)`
-**Details**:
+**Details**:
Underscorify the string (replace - and . by _)
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/string#L103)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/string#L103)
[/details]
-----------------
+
+---
+
## SYSTEMD
-#### ynh_add_systemd_config
-
+### ynh_add_systemd_config
[details summary="Create a dedicated systemd config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_add_systemd_config [--service=service] [--template=template]`
**Arguments**:
-
- `-s`, `--service=`: Service name (optionnal, `$app` by default)
- `-t`, `--template=`: Name of template file (optionnal, this is 'systemd' by default, meaning `../conf/systemd.service` will be used as template)
-**Details**:
+**Details**:
This will use the template `../conf/.service`.
See the documentation of `ynh_add_config` for a description of the template
@@ -2019,35 +2062,35 @@ format and how placeholders are replaced with actual variables.
Requires YunoHost version 4.1.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/systemd#L15)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/systemd#L15)
[/details]
-----------------
-#### ynh_remove_systemd_config
+---
+### ynh_remove_systemd_config
[details summary="Remove the dedicated systemd config" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_remove_systemd_config [--service=service]`
**Arguments**:
-
- `-s`, `--service=`: Service name (optionnal, $app by default)
-**Details**:
+**Details**:
Requires YunoHost version 2.7.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/systemd#L38)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/systemd#L38)
[/details]
-----------------
-#### ynh_systemd_action
+---
+### ynh_systemd_action
[details summary="Start (or other actions) a service, print a log in case of failure and optionnaly wait until the service is completely started" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_systemd_action [--service_name=service_name] [--action=action] [ [--line_match="line to match"] [--log_path=log_path] [--timeout=300] [--length=20] ]`
**Arguments**:
-
- `-n`, `--service_name=`: Name of the service to start. Default : `$app`
- `-a`, `--action=`: Action to perform with systemctl. Default: start
- `-l`, `--line_match=`: Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started.
@@ -2055,44 +2098,45 @@ Requires YunoHost version 2.7.2 or higher.
- `-t`, `--timeout=`: Timeout - The maximum time to wait before ending the watching. Default : 300 seconds.
- `-e`, `--length=`: Length of the error log displayed for debugging : Default : 20
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/systemd#L67)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/systemd#L67)
[/details]
-----------------
+
+---
+
## USER
-#### ynh_user_exists
-
+### ynh_user_exists
[details summary="Check if a YunoHost user exists" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_user_exists --username=username`
**Arguments**:
-
- `-u`, `--username=`: the username to check
**Returns**: 0 if the user exists, 1 otherwise.
**Example**: `ynh_user_exists 'toto' || echo "User does not exist"`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L12)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L12)
[/details]
-----------------
-#### ynh_user_get_info
+---
+### ynh_user_get_info
[details summary="Retrieve a YunoHost user information" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_user_get_info --username=username --key=key`
**Arguments**:
-
- `-u`, `--username=`: the username to retrieve info from
- `-k`, `--key=`: the key to retrieve
@@ -2100,15 +2144,16 @@ Requires YunoHost version 2.2.4 or higher.
**Example**: `mail=$(ynh_user_get_info --username="toto" --key=mail)`
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L33)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L33)
[/details]
-----------------
-#### ynh_user_list
+---
+### ynh_user_list
[details summary="Get the list of YunoHost users" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_user_list`
@@ -2117,147 +2162,146 @@ Requires YunoHost version 2.2.4 or higher.
**Example**: `for u in $(ynh_user_list); do ... ; done`
-**Details**:
+**Details**:
Requires YunoHost version 2.4.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L53)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L53)
[/details]
-----------------
-#### ynh_system_user_exists
+---
+### ynh_system_user_exists
[details summary="Check if a user exists on the system" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_system_user_exists --username=username`
**Arguments**:
-
- `-u`, `--username=`: the username to check
**Returns**: 0 if the user exists, 1 otherwise.
-**Details**:
+**Details**:
Requires YunoHost version 2.2.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L64)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L64)
[/details]
-----------------
-#### ynh_system_group_exists
+---
+### ynh_system_group_exists
[details summary="Check if a group exists on the system" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_system_group_exists --group=group`
**Arguments**:
-
- `-g`, `--group=`: the group to check
**Returns**: 0 if the group exists, 1 otherwise.
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0.2 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L82)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L82)
[/details]
-----------------
-#### ynh_system_user_create
+---
+### ynh_system_user_create
[details summary="Create a system user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] [--groups="group1 group2"]`
**Arguments**:
-
- `-u`, `--username=`: Name of the system user that will be create
- `-h`, `--home_dir=`: Path of the home dir for the user. Usually the final path of the app. If this argument is omitted, the user will be created without home
- `-s`, `--use_shell`: Create a user using the default login shell if present. If this argument is omitted, the user will be created with /usr/sbin/nologin shell
- `-g`, `--groups`: Add the user to system groups. Typically meant to add the user to the ssh.app / sftp.app group (e.g. for borgserver, my_webapp)
-**Details**:
+**Details**:
Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability) :
-
```
ynh_system_user_create --username=nextcloud
```
-
Create a discourse user using /var/www/discourse as home directory and the default login shell :
-
```
ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell
```
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L111)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L111)
[/details]
-----------------
-#### ynh_system_user_delete
+---
+### ynh_system_user_delete
[details summary="Delete a system user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_system_user_delete --username=user_name`
**Arguments**:
-
- `-u`, `--username=`: Name of the system user that will be create
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L153)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L153)
[/details]
-----------------
-#### ynh_exec_as
+---
+### ynh_exec_as
[details summary="Execute a command as another user" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_exec_as $USER COMMAND [ARG ...]`
-**Details**:
+**Details**:
Requires YunoHost version 4.1.7 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/user#L179)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/user#L179)
[/details]
-----------------
+
+---
+
## UTILS
-#### ynh_abort_if_errors
-
+### ynh_abort_if_errors
[details summary="Exits if an error occurs during the execution of the script." class="helper-card-subtitle text-muted"]
**Usage**: `ynh_abort_if_errors`
-**Details**:
+**Details**:
This configure the rest of the script execution such that, if an error occurs
or if an empty variable is used, the execution of the script stops immediately
and a call to `ynh_clean_setup` is triggered if it has been defined by your script.
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L61)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L61)
[/details]
-----------------
-#### ynh_setup_source
+---
+### ynh_setup_source
[details summary="Download, check integrity, uncompress and patch the source from app.src" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_setup_source --dest_dir=dest_dir [--source_id=source_id] [--keep="file1 file2"] [--full_replace]`
**Arguments**:
-
- `-d`, `--dest_dir=`: Directory where to setup sources
- `-s`, `--source_id=`: Name of the source, defaults to `main` (when the sources resource exists in manifest.toml) or (legacy) `app` otherwise
- `-k`, `--keep=`: Space-separated list of files/folders that will be backup/restored in $dest_dir, such as a config file you don't want to overwrite. For example 'conf.json secrets.json logs' (no trailing `/` for folders)
- `-r`, `--full_replace=`: Remove previous sources before installing new sources
-**Details**:
-
+**Details**:
#### New 'sources' resources
(See also the resources documentation which may be more complete?)
@@ -2293,7 +2337,6 @@ platform = "linux/amd64" # (defaults to "linux/$YNH_ARCH") to be used
```
You may also define assets url and checksum per-architectures such as:
-
```toml
[resources.sources]
[resources.sources.main]
@@ -2305,12 +2348,13 @@ You may also define assets url and checksum per-architectures such as:
In which case ynh_setup_source --dest_dir="$install_dir" will automatically pick the appropriate source depending on the arch
+
+
#### Legacy format '.src'
This helper will read `conf/${source_id}.src`, download and install the sources.
The src file need to contains:
-
```
SOURCE_URL=Address to download the app archive
SOURCE_SUM=Sha256 sum
@@ -2322,7 +2366,6 @@ SOURCE_PLATFORM=linux/arm64/v8
```
The helper will:
-
- Download the specific URL if there is no local archive
- Check the integrity with the specific sha256 sum
- Uncompress the archive to `$dest_dir`.
@@ -2333,18 +2376,18 @@ The helper will:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L154)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L154)
[/details]
-----------------
-#### ynh_local_curl
+---
+### ynh_local_curl
[details summary="Curl abstraction to help with POST requests to local pages (such as installation forms)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_local_curl "page_uri" "key1=value1" "key2=value2" ...`
**Arguments**:
-
- `page_uri`: Path (relative to `$path_url`) of the page where POST data will be sent
- `key1=value1`: (Optionnal) POST key and corresponding value
- `key2=value2`: (Optionnal) Another POST key and corresponding value
@@ -2352,42 +2395,46 @@ Requires YunoHost version 2.6.4 or higher.
**Example**: `ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2"`
-**Details**:
+**Details**:
For multiple calls, cookies are persisted between each call for the same app
`$domain` and `$path_url` should be defined externally (and correspond to the domain.tld and the /path (of the app?))
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L404)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L404)
[/details]
-----------------
-#### ynh_add_config
+---
+### ynh_add_config
[details summary="Create a dedicated config file from a template" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_add_config --template="template" --destination="destination"`
**Arguments**:
-
- `-t`, `--template=`: Template config file to use
- `-d`, `--destination=`: Destination of the config file
**Examples**:
+
+
+- ` ynh_add_config --template=".env" --destination="$install_dir/.env" use the template file "../conf/.env"`
+
+
+
+- ` ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf"`
+
+
-- `ynh_add_config --template=".env" --destination="$install_dir/.env" use the template file "../conf/.env"`
-
-- `ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf"`
-
-**Details**:
+**Details**:
The template can be by default the name of a file in the conf directory
of a YunoHost Package, a relative path or an absolute path.
The helper will use the template `template` to generate a config file
`destination` by replacing the following keywords with global variables
that should be defined before calling this helper :
-
```
__PATH__ by $path_url
__NAME__ by $app
@@ -2397,9 +2444,7 @@ that should be defined before calling this helper :
__PHPVERSION__ by $YNH_PHP_VERSION (packaging v1 only, packaging v2 uses phpversion setting implicitly set by apt resource)
__YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH
```
-
And any dynamic variables that should be defined before calling this helper like:
-
```
__DOMAIN__ by $domain
__APP__ by $app
@@ -2415,23 +2460,23 @@ into the app settings when configuration is done.
Requires YunoHost version 4.1.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L488)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L488)
[/details]
-----------------
-#### ynh_read_var_in_file
+---
+### ynh_read_var_in_file
[details summary="Get a value from heterogeneous file (yaml, json, php, python...)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_read_var_in_file --file=PATH --key=KEY`
**Arguments**:
-
- `-f`, `--file=`: the path to the file
- `-k`, `--key=`: the key to get
- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file)
-**Details**:
+**Details**:
This helpers match several var affectation use case in several languages
We don't use jq or equivalent to keep comments and blank space in files
This helpers work line by line, it is not able to work correctly
@@ -2440,7 +2485,7 @@ if you have several identical keys in your files
Example of line this helpers can managed correctly
.yml
title: YunoHost documentation
- email: ''
+ email: 'yunohost@yunohost.org'
.json
"theme": "colib'ris",
"port": 8102
@@ -2455,100 +2500,101 @@ Example of line this helpers can managed correctly
user => 20
.py
USER = 8102
- user = ''
+ user = 'https://donate.local'
CUSTOM['user'] = 'YunoHost'
Requires YunoHost version 4.3 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L646)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L646)
[/details]
-----------------
-#### ynh_write_var_in_file
+---
+### ynh_write_var_in_file
[details summary="Set a value into heterogeneous file (yaml, json, php, python...)" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_write_var_in_file --file=PATH --key=KEY --value=VALUE`
**Arguments**:
-
- `-f`, `--file=`: the path to the file
- `-k`, `--key=`: the key to set
- `-v`, `--value=`: the value to set
- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file)
-**Details**:
+**Details**:
Requires YunoHost version 4.3 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L724)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L724)
[/details]
-----------------
-#### ynh_get_debian_release
+---
+### ynh_get_debian_release
[details summary="Fetch the Debian release codename" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_get_debian_release`
**Returns**: The Debian release codename (i.e. jessie, stretch, ...)
-**Details**:
+**Details**:
Requires YunoHost version 2.7.12 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L839)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L839)
[/details]
-----------------
-#### ynh_secure_remove
+---
+### ynh_secure_remove
[details summary="Remove a file or a directory securely" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_secure_remove --file=path_to_remove`
**Arguments**:
-
- `-f`, `--file=`: File or directory to remove
-**Details**:
+**Details**:
Requires YunoHost version 2.6.4 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L870)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L870)
[/details]
-----------------
-#### ynh_read_manifest
+---
+### ynh_read_manifest
[details summary="Read the value of a key in a ynh manifest file" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_read_manifest --manifest="manifest.json" --key="key"`
**Arguments**:
-
- `-m`, `--manifest=`: Path of the manifest to read
- `-k`, `--key=`: Name of the key to find
**Returns**: the value associate to that key
-**Details**:
+**Details**:
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L904)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L904)
[/details]
-----------------
-#### ynh_app_upstream_version
+---
+### ynh_app_upstream_version
[details summary="Read the upstream version from the manifest or `$YNH_APP_MANIFEST_VERSION`" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_app_upstream_version [--manifest="manifest.json"]`
**Arguments**:
-
- `-m`, `--manifest=`: Path of the manifest to read
**Returns**: the version number of the upstream app
-**Details**:
+**Details**:
If the `manifest` is not specified, the envvar `$YNH_APP_MANIFEST_VERSION` will be used.
The version number in the manifest is defined by `~ynh`.
@@ -2557,71 +2603,71 @@ For example, if the manifest contains `4.3-2~ynh3` the function will return `4.3
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L947)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L947)
[/details]
-----------------
-#### ynh_app_package_version
+---
+### ynh_app_package_version
[details summary="Read package version from the manifest" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_app_package_version [--manifest="manifest.json"]`
**Arguments**:
-
- `-m`, `--manifest=`: Path of the manifest to read
**Returns**: the version number of the package
-**Details**:
+**Details**:
The version number in the manifest is defined by `~ynh`.
For example, if the manifest contains `4.3-2~ynh3` the function will return `3`
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L976)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L976)
[/details]
-----------------
-#### ynh_check_app_version_changed
+---
+### ynh_check_app_version_changed
[details summary="Checks the app version to upgrade with the existing app version and returns:" class="helper-card-subtitle text-muted"]
**Usage**: `ynh_check_app_version_changed`
**Returns**: `UPGRADE_APP` if the upstream version changed, `UPGRADE_PACKAGE` otherwise.
-**Details**:
+**Details**:
This helper should be used to avoid an upgrade of an app, or the upstream part
of it, when it's not needed
Requires YunoHost version 3.5.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L997)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L997)
[/details]
-----------------
-#### ynh_compare_current_package_version
+---
+### ynh_compare_current_package_version
[details summary="Compare the current package version against another version given as an argument." class="helper-card-subtitle text-muted"]
**Usage**: `ynh_compare_current_package_version --comparison (lt|le|eq|ne|ge|gt) --version `
**Arguments**:
-
- `--comparison`: Comparison type. Could be : `lt` (lower than), `le` (lower or equal), `eq` (equal), `ne` (not equal), `ge` (greater or equal), `gt` (greater than)
-- `--version`: The version to compare. Need to be a version in the YunoHost package version type (like `2.3.1~ynh4`)
+- `--version`: The version to compare. Need to be a version in the yunohost package version type (like `2.3.1~ynh4`)
**Returns**: 0 if the evaluation is true, 1 if false.
**Example**: `ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1`
-**Details**:
+**Details**:
This helper is usually used when we need to do some actions only for some old package versions.
Generally you might probably use it as follow in the upgrade script :
-
```
if ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1
then
@@ -2631,6 +2677,9 @@ fi
Requires YunoHost version 3.8.0 or higher.
-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/helpers/utils#L1027)
+
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/helpers/utils#L1027)
[/details]
-----------------
+
+---
+
diff --git a/pages/06.contribute/10.packaging_apps/80.resources/15.appresources/packaging_apps_resources.md b/pages/06.contribute/10.packaging_apps/80.resources/15.appresources/packaging_apps_resources.md
index e1a80b99..301e79f8 100644
--- a/pages/06.contribute/10.packaging_apps/80.resources/15.appresources/packaging_apps_resources.md
+++ b/pages/06.contribute/10.packaging_apps/80.resources/15.appresources/packaging_apps_resources.md
@@ -7,16 +7,16 @@ routes:
default: '/packaging_apps_resources'
---
-Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/4759ff66a7c93df2f654c11086585131744ad61d/doc/generate_resource_doc.py) on 01/03/2024 (YunoHost version 11.2.10.3)
+Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/bf5b2ae53296b61310f5b728f185763fe2e81765/doc/generate_resource_doc.py) on 11/04/2024 (YunoHost version 11.2.11.1)
-----------------
+
+---
## 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
-
+### Example
```toml
[resources.apt]
packages = ["nyancat", "lolcat", "sl"]
@@ -27,60 +27,52 @@ extras.yarn.key = "https://dl.yarnpkg.com/debian/pubkey.gpg"
extras.yarn.packages = ["yarn"]
```
-##### Properties
-
+### 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
-
+### 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
-
+### 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
-
+### Example
```toml
[resources.data_dir]
# (empty - defaults are usually okay)
```
-##### Properties
-
+### 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
-
+### 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
-
+### 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
-
+### 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
@@ -90,69 +82,59 @@ NB: only one DB can be handled in such a way (is there really an app that would
NB2: no automagic migration will happen in an suddenly change `type` from `mysql` to `postgresql` or viceversa in its life
-##### Example
-
+### Example
```toml
[resources.database]
type = "mysql" # or : "postgresql". Only these two values are supported
```
-##### Properties
-
+### Properties
- `type`: The database type, either `mysql` or `postgresql`
-##### Provision/Update
-
+### 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
-
+### 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
-
+### 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
-
+### Example
```toml
[resources.install_dir]
# (empty - defaults are usually okay)
```
-##### Properties
-
+### 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
-
+### 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
-
+### Deprovision
- recursively deletes the directory if it exists
-##### Legacy management
-
+### 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
@@ -162,8 +144,7 @@ Additional permissions can be created, typically to have a specific tile and/or
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
-
+### Example
```toml
[resources.permissions]
main.url = "/"
@@ -174,8 +155,7 @@ admin.show_tile = false
admin.allowed = "admins" # Assuming the "admins" group exists (cf future developments ;))
```
-##### Properties (for each perm name)
-
+### 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.
@@ -183,20 +163,17 @@ admin.allowed = "admins" # Assuming the "admins" group exists (cf future devel
- `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
-
+### 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
-
+### Deprovision
- Delete all permission related to this app
-##### Legacy management
-
+### Legacy management
- Legacy `is_public` setting will be deleted if it exists
-----------------
+---
## Ports
@@ -204,8 +181,7 @@ Book port(s) to be used by the app, typically to be used to the internal reverse
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
-
+### Example
```toml
[resources.ports]
# (empty should be fine for most apps... though you can customize stuff if absolutely needed)
@@ -217,28 +193,24 @@ xmpp_client.default = 5222 # if you need another port, pick a name for it (here
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)
-
+### 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)
-
+### 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 `NAME`s
-##### Deprovision
-
+### Deprovision
- Close the ports on the firewall if relevant
- Deletes all the port settings
-##### Legacy management
-
+### 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
@@ -248,7 +220,7 @@ This resource is intended both to declare the assets, which will be parsed by yn
Various options are available to accomodate the behavior according to the asset structure
-##### Example
+### Example
```toml
[resources.sources]
@@ -287,26 +259,26 @@ Or more complex examples with several element, including one with asset that dep
```
-##### Properties (for each source)
+### 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
+ - 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`, ...
+ - 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 ...)
+ - `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 `mv`ed 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`
+#### 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.
+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 : which is ran by the YunoHost infrastructure periodically and will create the corresponding pull request automatically.
@@ -326,11 +298,12 @@ And choose one strategy in the following ones:
- `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__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__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.
+- `latest__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.
+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:
```toml
@@ -339,39 +312,34 @@ autoupdate.version_regex = "^release-v(.*)$"
And the autoupdater will use the matched group (here: `4.1`) as the version.
-##### Provision/Update
-
+### 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
-
+### 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
-
+### Example
```toml
[resources.system_user]
# (empty - defaults are usually okay)
```
-##### Properties
-
+### 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
-
+### Provision/Update
- will create the system user if it doesn't exists yet
- will add/remove the ssh/sftp.app groups
-##### Deprovision
-
+### Deprovision
- deletes the user and group
+