Doc auto-generated by this script on 03/07/2024 (YunoHost version 11.2.20.2)
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
)
[resources.apt]
packages = ["nyancat", "lolcat", "sl"]
# (this part is optional and corresponds to the legacy ynh_install_extra_app_dependencies helper)
extras.yarn.repo = "deb https://dl.yarnpkg.com/debian/ stable main"
extras.yarn.key = "https://dl.yarnpkg.com/debian/pubkey.gpg"
extras.yarn.packages = ["yarn"]
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 fromynh_install_app_dependencies
and ynh_install_extra_app_dependencies
, similar to what happens in v1.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__
)ynh_remove_app_dependencies
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.
[resources.data_dir]
# (empty - defaults are usually okay)
dir
: (default: /home/yunohost.app/__APP__
) The full path of the data dirsubdirs
: (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 dirgroup
: (default: __APP__:rx
) The group (and group permissions) for the data dirmv
'ed to the new locationdir
as data_dir
in the app's settings, which can be then used by the app scripts ($data_dir
) and conf templates (__DATA_DIR__
)datadir
. The code will automatically rename it as data_dir
.Initialize a database, either using MySQL or Postgresql. Relevant DB infos are stored in settings $db_name
, $db_user
and $db_pwd
.
NB: only one DB can be handled in such a way (is there really an app that would need two completely different DB ?...)
NB2: no automagic migration will happen in an suddenly change type
from mysql
to postgresql
or viceversa in its life
[resources.database]
type = "mysql" # or : "postgresql". Only these two values are supported
type
: The database type, either mysql
or postgresql
$db_name
and $db_user
settings with the sanitized app name (replacing -
and .
with _
)$db_pwd
doesn't already exists, pick a random database password and store it in that settingynh_mysql_create_db
or ynh_psql_create_db
.ynh_mysql_remove_db
or ynh_psql_remove_db
db_name
, db_user
and db_pwd
settingsmysqlpwd
or psqlpwd
, in which case it will automatically be renamed as db_pwd
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
[resources.install_dir]
# (empty - defaults are usually okay)
dir
: (default: /var/www/__APP__
) The full path of the install dirowner
: (default: __APP__:rwx
) The owner (and owner permissions) for the install dirgroup
: (default: __APP__:rx
) The group (and group permissions) for the install dirmv
'ed to the new locationdir
as install_dir
in the app's settings, which can be then used by the app scripts ($install_dir
) and conf templates (__INSTALL_DIR__
)final_path
. The code will automatically rename it as install_dir
.Configure the SSO permissions/tiles. Typically, webapps are expected to have a 'main' permission mapped to '/', meaning that a tile pointing to the $domain/$path
will be available in the SSO for users allowed to access that app.
Additional permissions can be created, typically to have a specific tile and/or access rules for the admin part of a webapp.
The list of allowed user/groups may be initialized using the content of the init_{perm}_permission
question from the manifest, hence init_main_permission
replaces the is_public
question and shall contain a group name (typically, all_users
or visitors
).
[resources.permissions]
main.url = "/"
# (these two previous lines should be enough in the majority of cases)
admin.url = "/admin"
admin.show_tile = false
admin.allowed = "admins" # Assuming the "admins" group exists (cf future developments ;))
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 portalallowed
: (default: nobody) The group initially allowed to access this perm, if init_{perm}_permission
is not defined in the manifest questions. Note that the admin may tweak who is allowed/unallowed on that permission later on, this is only meant to initialize the permission.auth_header
: (default: true
) Define for the URL of this permission, if SSOwat pass the authentication header to the application. Default is trueprotected
: (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/forbiddenis_public
setting will be deleted if it existsBook port(s) to be used by the app, typically to be used to the internal reverse-proxy between nginx and the app process.
Note that because multiple ports can be booked, each properties is prefixed by the name of the port. main
is a special name and will correspond to the setting $port
, whereas for example xmpp_client
will correspond to the setting $port_xmpp_client
.
[resources.ports]
# (empty should be fine for most apps... though you can customize stuff if absolutely needed)
main.default = 12345 # if you really want to specify a prefered value .. but shouldnt matter in the majority of cases
xmpp_client.default = 5222 # if you need another port, pick a name for it (here, "xmpp_client")
xmpp_client.exposed = "TCP" # here, we're telling that the port needs to be publicly exposed on TCP on the firewall
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 protocoldefault
value (or a random value between 10000 and 60000 if no default
set)exposed
is not false
, open the port in the firewall accordingly - otherwise make sure it's closed.$port
setting for the main
port, or $port_NAME
for other NAME
sNAME_port
instead of port_NAME
, in which case the code will automatically rename the old setting.Declare what are the sources / assets used by this app. Typically, this corresponds to some tarball published by the upstream project, that needs to be downloaded and extracted in the install dir using the ynh_setup_source helper.
This resource is intended both to declare the assets, which will be parsed by ynh_setup_source during the app script runtime, AND to prefetch and validate the sha256sum of those asset before actually running the script, to be able to report an error early when the asset turns out to not be available for some reason.
Various options are available to accomodate the behavior according to the asset structure
[resources.sources]
[resources.sources.main]
url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.tar.gz"
sha256 = "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
autoupdate.strategy = "latest_github_tag"
Or more complex examples with several element, including one with asset that depends on the arch
[resources.sources]
[resources.sources.main]
in_subdir = false
amd64.url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.amd64.tar.gz"
amd64.sha256 = "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
i386.url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.386.tar.gz"
i386.sha256 = "53c234e5e8472b6ac51c1ae1cab3fe06fad053beb8ebfd8977b010655bfdd3c3"
armhf.url = "https://github.com/foo/bar/archive/refs/tags/v1.2.3.arm.tar.gz"
armhf.sha256 = "4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865"
autoupdate.strategy = "latest_github_release"
autoupdate.asset.amd64 = ".*\.amd64.tar.gz"
autoupdate.asset.i386 = ".*\.386.tar.gz"
autoupdate.asset.armhf = ".*\.arm.tar.gz"
[resources.sources.zblerg]
url = "https://zblerg.com/download/zblerg"
sha256 = "1121cfccd5913f0a63fec40a6ffd44ea64f9dc135c66634ba001d10bcf4302a2"
format = "script"
rename = "zblerg.sh"
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
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 manifestsha256
: 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...
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 archivezip
: will use unzip
to extract the archivedocker
: 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 filesextract
: 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
valuerename
: some string like whatever_your_want
, to be used for convenience when extract
is false
and the default name of the file is not practicalplatform
: for example linux/amd64
(defaults to linux/$YNH_ARCH
) to be used in conjonction with format = "docker"
to specify which architecture to extract forautoupdate
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 script will rely on the code repo specified in code
in the upstream section of the manifest.
The autoupdate.strategy
is expected to be constructed like this: latest_<gitforge>_<strategy>
You need to replace the <gitforge>
in the strategy name by either github
, gitlab
, gitea
or forgejo
, as the autoupdater supports:
And choose one strategy in the following ones:
latest_<gitforge>_release
: similar to latest_<gitforge>_tag
, but starting from the list of releases. Note that it's the only strategy that provides the changelog link in the PR message. Pre- or draft releases are ignored. Releases may have assets attached to them, in which case you can define:
autoupdate.asset = "some regex"
(when there's only one asset to use). The regex is used to find the appropriate asset among the list of all assetsautoupdate.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 assetslatest_<gitforge>_tag
: look for the latest tag (by sorting tags and finding the "largest" version). Then using the corresponding tar.gz url. Tags containing rc
, beta
, alpha
, start
are ignored, and actually any tag which doesn't look like x.y.z
or vx.y.z
latest_<gitforge>_commit
: will use the latest commit on github, and the corresponding tarball. If this is used for the 'main' source, it will also assume that the version is YYYY.MM.DD corresponding to the date of the commit.It is also possible to define autoupdate.upstream
to use a different Git repository instead of the code repository from the upstream section of the manifest. This can be useful when, for example, the app uses other assets such as plugin from a different repository.
If the upstream project provides non-standard tag or release names, you can fix this, with a regex with a matching group.
For example, if tags look like release-v4.1
, put:
autoupdate.version_regex = "^release-v(.*)$"
And the autoupdater will use the matched group (here: 4.1
) as the version.
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)Provision a system user to be used by the app. The username is exactly equal to the app id
[resources.system_user]
# (empty - defaults are usually okay)
allow_ssh
: (default: False) Adds the user to the ssh.app group, allowing SSH connection via this userallow_sftp
: (default: False) Adds the user to the sftp.app group, allowing SFTP connection via this userallow_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 nowFehler gefunden? Möchten Sie diese Seite verbessern? Einfach dem Edit Link am Anfang der Seite folgen und dann auf das Symbol auf Github clicken um Änderungen vorzuschlagen.
Powered by Grav + with by Trilby Media. • Terms of Service