YunoHost/doc
1
0
Fork 0
mirror of https://github.com/YunoHost/doc.git synced 2024-09-03 20:06:26 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'YunoHost:master' into master

Browse source
This commit is contained in:
Leandro Noferini 2024-04-17 07:25:26 +02:00 • committed by GitHub
commit 692580055a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 731 additions and 714 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
pages/02.administer/45.tutorials/45.certificate_custom/certificate_custom.md
View file

@ -123,7 +123,7 @@ kSK6OOauBHItgiGI7C87u4EJaHDvGIUxHxQQGsUM0SCIIVGK7Lwm+8e9I2X0G2GP
Finally, secure your certificate files. Finally, secure your certificate files.
```bash ```bash
sudo chown root:metronome crt.pem key.pem sudo chown root:ssl-cert crt.pem key.pem
sudo chmod 640 crt.pem key.pem sudo chmod 640 crt.pem key.pem
sudo chown root:root -R ae_certs sudo chown root:root -R ae_certs
sudo chmod 600 -R ae_certs sudo chmod 600 -R ae_certs

4
pages/02.administer/55.providers/15.vpn/vpn.md
View file

@ -27,7 +27,7 @@ Below, you can find a list of providers compatible for self-hosting and especial
| VPN provider | [VPNClient](https://github.com/labriqueinternet/vpnclient_ynh) compatibility | IPv6 | rDNS IPv4 | rDNS IPv6 | Price | Membership | Net Neutrality | | VPN provider | [VPNClient](https://github.com/labriqueinternet/vpnclient_ynh) compatibility | IPv6 | rDNS IPv4 | rDNS IPv6 | Price | Membership | Net Neutrality |
| ------------ | ----------------------- | ---- | --------- | --------- | ----- | -------------- | | ------------ | ----------------------- | ---- | --------- | --------- | ----- | -------------- |
| [Neutrinet](https://neutrinet.be/en/vpn) | ✔ (.cube + [internetcube](https://internetcu.be)) | ✔ | ✔ | ? | ~8 €¹ / month | included | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> | | [Neutrinet](https://neutrinet.be/en/vpn) | ✔ (.cube + [internetcube](https://internetcu.be)) | ✔ | ✔ | ✔ | ~10 €¹ / month | 10€ or 30€ / year | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> |
¹ [Pay what you want](https://en.wikipedia.org/wiki/Pay_what_you_want) ¹ [Pay what you want](https://en.wikipedia.org/wiki/Pay_what_you_want)
!!! If you try an other VPN provider that include **public dedicated ipv4 and port forwarding**, feel free to contribute to this documentation. We need people to test specific offers of those commercial providers: !!! If you try an other VPN provider that include **public dedicated ipv4 and port forwarding**, feel free to contribute to this documentation. We need people to test specific offers of those commercial providers:
@ -52,7 +52,7 @@ Below, you can find a list of providers compatible for self-hosting and especial
| [ILOTH](https://iloth.net/vpn/) | ✔ (.cube) | ✘ | ✔ | ✘ | 80€ / an | 5 à 100€ / an | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> | | [ILOTH](https://iloth.net/vpn/) | ✔ (.cube) | ✘ | ✔ | ✘ | 80€ / an | 5 à 100€ / an | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> |
| [Milkywan](https://milkywan.fr/prices#popupTunnel) | ✔ (manuelle) | ✔ | ✔ | ✔ | 5 € / mois | incluse | <span class="label label-success label-as-badge">Non Profit</span> | | [Milkywan](https://milkywan.fr/prices#popupTunnel) | ✔ (manuelle) | ✔ | ✔ | ✔ | 5 € / mois | incluse | <span class="label label-success label-as-badge">Non Profit</span> |
| [Mycélium](https://mycelium-fai.org/wiki/documentation/services/vpn) | ✔ (manuelle) | ✘ | ✘ | ✘ | Prix libre | incluse<br>Réservé aux nordistes(FR 59) | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> | | [Mycélium](https://mycelium-fai.org/wiki/documentation/services/vpn) | ✔ (manuelle) | ✘ | ✘ | ✘ | Prix libre | incluse<br>Réservé aux nordistes(FR 59) | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> |
| [Neutrinet](https://neutrinet.be/en/vpn) | ✔ (.cube + [internetcube](https://internetcu.be)) | ✔ | ✔ | ? | ~8 €¹ / mois | incluse | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> | | [Neutrinet](https://neutrinet.be/en/vpn) | ✔ (.cube + [internetcube](https://internetcu.be)) | ✔ | ✔ | ✔ | ~10 €¹ / mois | 10 € ou 30 € / an | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> |
| [Rézine](https://www.rezine.org/acces_internet/tunnels_chiffr%C3%A9s/) | ✔ (manuelle) | ✔ | ✔ | ✔ | 5 à 10€ / mois | Prix libre | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> | | [Rézine](https://www.rezine.org/acces_internet/tunnels_chiffr%C3%A9s/) | ✔ (manuelle) | ✔ | ✔ | ✔ | 5 à 10€ / mois | Prix libre | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> |
| [Swiss Neutral Network](https://www.swissneutral.net/?page_id=31) | ✔ (.cube) | ✔ | ✔ | ✔ | 30.- CHF/mois | 50.- CHF / an<br>Réservé aux suisses | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> | | [Swiss Neutral Network](https://www.swissneutral.net/?page_id=31) | ✔ (.cube) | ✔ | ✔ | ✔ | 30.- CHF/mois | 50.- CHF / an<br>Réservé aux suisses | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> |
| [Tetaneutral](https://tetaneutral.net/adherer/) | ✘ (wireguard) | ? | ? | ? | 5€¹ / mois | 5 à 100€¹ / an | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> | | [Tetaneutral](https://tetaneutral.net/adherer/) | ✘ (wireguard) | ? | ? | ? | 5€¹ / mois | 5 à 100€¹ / an | <span class="ffdn">FFDN</span> <span class="label label-success label-as-badge">Non Profit</span> |

1289
pages/06.contribute/10.packaging_apps/80.resources/11.helpers/packaging_apps_helpers.md
View file

File diff suppressed because it is too large Load diff

150
pages/06.contribute/10.packaging_apps/80.resources/15.appresources/packaging_apps_resources.md
View file

@ -7,16 +7,16 @@ routes:
default: '/packaging_apps_resources' 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/7d0d82ae016ae3e7cdb06423b67678d7f7a5d9ca/doc/generate_resource_doc.py) on 11/04/2024 (YunoHost version 11.2.11.2)
----------------
---
## Apt ## 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`) 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 ```toml
[resources.apt] [resources.apt]
packages = ["nyancat", "lolcat", "sl"] packages = ["nyancat", "lolcat", "sl"]
@ -27,60 +27,52 @@ extras.yarn.key = "https://dl.yarnpkg.com/debian/pubkey.gpg"
extras.yarn.packages = ["yarn"] extras.yarn.packages = ["yarn"]
``` ```
##### Properties ### Properties
- `packages`: List of packages to be installed via `apt` - `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. - `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 - `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. - 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__`) - 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` - The code literally calls the bash helper `ynh_remove_app_dependencies`
---------------- ---
## Data Dir ## 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. 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 ```toml
[resources.data_dir] [resources.data_dir]
# (empty - defaults are usually okay) # (empty - defaults are usually okay)
``` ```
##### Properties ### Properties
- `dir`: (default: `/home/yunohost.app/__APP__`) The full path of the data dir - `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']` - `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 - `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 - `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 - 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 - otherwise, creates the directory if it doesn't exists yet
- create each subdir declared and which do not exist already - create each subdir declared and which do not exist already
- (re-)apply permissions (only on the folder itself and declared subdirs, not recursively) - (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__`) - 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 - (only if the purge option is chosen by the user) recursively deletes the directory if it exists
- also delete the corresponding setting - 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`. - 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 - As explained in the 'Provision/Update' section, the folder will also be moved if the location changed
---------------- ---
## Database ## 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 NB2: no automagic migration will happen in an suddenly change `type` from `mysql` to `postgresql` or viceversa in its life
##### Example ### Example
```toml ```toml
[resources.database] [resources.database]
type = "mysql" # or : "postgresql". Only these two values are supported type = "mysql" # or : "postgresql". Only these two values are supported
``` ```
##### Properties ### Properties
- `type`: The database type, either `mysql` or `postgresql` - `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 `_`) - (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 `$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`. - 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` - Drop the DB using `ynh_mysql_remove_db` or `ynh_psql_remove_db`
- Deletes the `db_name`, `db_user` and `db_pwd` settings - 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` - 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 ## 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` 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 ```toml
[resources.install_dir] [resources.install_dir]
# (empty - defaults are usually okay) # (empty - defaults are usually okay)
``` ```
##### Properties ### Properties
- `dir`: (default: `/var/www/__APP__`) The full path of the install dir - `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 - `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 - `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?) - 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 - 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 - otherwise, creates the directory if it doesn't exists yet
- (re-)apply permissions (only on the folder itself, not recursively) - (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__`) - 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 - 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`. - 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 - As explained in the 'Provision/Update' section, the folder will also be moved if the location changed
---------------- ---
## Permissions ## 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`). 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 ```toml
[resources.permissions] [resources.permissions]
main.url = "/" main.url = "/"
@ -174,8 +155,7 @@ admin.show_tile = false
admin.allowed = "admins" # Assuming the "admins" group exists (cf future developments ;)) 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. - `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 - `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. - `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'. - `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 - `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 - 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 - 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 - Delete all permission related to this app
##### Legacy management ### Legacy management
- Legacy `is_public` setting will be deleted if it exists - Legacy `is_public` setting will be deleted if it exists
---------------- ---
## Ports ## 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`. 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 ```toml
[resources.ports] [resources.ports]
# (empty should be fine for most apps... though you can customize stuff if absolutely needed) # (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 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. - `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. - `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 - `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 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. - 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 - 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 - Close the ports on the firewall if relevant
- Deletes all the port settings - 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. - 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 ## 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 Various options are available to accomodate the behavior according to the asset structure
##### Example ### Example
```toml ```toml
[resources.sources] [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. - `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 - `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... - `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: - `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 - `tar.gz`, `tar.xz`, `tar.bz2` : will use `tar` to extract the archive
- `zip` : will use `unzip` 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` - `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 ...) - `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 - `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 - `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 - `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 - `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 : <https://github.com/YunoHost/apps/blob/master/tools/autoupdate_app_sources/autoupdate_app_sources.py> which is ran by the YunoHost infrastructure periodically and will create the corresponding pull request automatically. The infos are used by this script : <https://github.com/YunoHost/apps/blob/master/tools/autoupdate_app_sources/autoupdate_app_sources.py> 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 - `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 - or several `autoupdate.asset.$arch = "some_regex"` (when the asset is arch-specific). The regex is used to find the appropriate asset for the specific arch among the list of assets
- `latest_<gitforge>_tag` : look for the latest tag (by sorting tags and finding the "largest" version). Then using the corresponding tar.gz url. Tags containing `rc`, `beta`, `alpha`, `start` are ignored, and actually any tag which doesn't look like `x.y.z` or `vx.y.z` - `latest_<gitforge>_tag` : look for the latest tag (by sorting tags and finding the "largest" version). Then using the corresponding tar.gz url. Tags containing `rc`, `beta`, `alpha`, `start` are ignored, and actually any tag which doesn't look like `x.y.z` or `vx.y.z`
- `latest_<gitforge>_commit` : will use the latest commit on GitHub, and the corresponding tarball. If this is used for the 'main' source, it will also assume that the version is YYYY.MM.DD corresponding to the date of the commit. - `latest_<gitforge>_commit` : will use the latest commit on github, and the corresponding tarball. If this is used for the 'main' source, it will also assume that the version is YYYY.MM.DD corresponding to the date of the commit.
It is also possible to define `autoupdate.upstream` to use a different Git repository instead of the code repository from the upstream section of the manifest. This can be useful when, for example, the app uses other assets such as plugin from a different repository. 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: For example, if tags look like `release-v4.1`, put:
```toml ```toml
@ -339,39 +312,34 @@ autoupdate.version_regex = "^release-v(.*)$"
And the autoupdater will use the matched group (here: `4.1`) as the version. 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) - 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) - Nothing (just cleanup the cache)
---------------- ---
## System User ## System User
Provision a system user to be used by the app. The username is exactly equal to the app id Provision a system user to be used by the app. The username is exactly equal to the app id
##### Example ### Example
```toml ```toml
[resources.system_user] [resources.system_user]
# (empty - defaults are usually okay) # (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_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_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` - `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 - `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 create the system user if it doesn't exists yet
- will add/remove the ssh/sftp.app groups - will add/remove the ssh/sftp.app groups
##### Deprovision ### Deprovision
- deletes the user and group - deletes the user and group