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

packaging v2: fix title level

Browse source
This commit is contained in:
Alexandre Aubin 2023-02-01 23:50:22 +01:00
parent 17d4472303
commit ba549a464b
5 changed files with 33 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
pages/06.contribute/10.packaging_apps/10.manifest/manifest.md
View file

@ -12,7 +12,7 @@ The app's `manifest.toml` can be seen as the ID card of the app. It declares var
In this page, the data are described according to a somewhat dummy app called `helloworld` In this page, the data are described according to a somewhat dummy app called `helloworld`
# General information ## General information
```toml ```toml
packaging_format = 2 packaging_format = 2
@ -43,7 +43,7 @@ maintainers = ["alexAubin"]
- `maintainers` (`list` or `str`) may allow to declare which person should be the referring person for this package (though packages are often maintained collectively and not really used in practice). This should contain a list of easily identifiable persons (eg your Github or Matrix username) - `maintainers` (`list` or `str`) may allow to declare which person should be the referring person for this package (though packages are often maintained collectively and not really used in practice). This should contain a list of easily identifiable persons (eg your Github or Matrix username)
# Upstream section ## Upstream section
This section is meant to provide various metadata about the app upstream such that YunoHost admins can easily obtain further information regarding this app (or, kinda important, try the upstream's demo before deciding to install it). This section is meant to provide various metadata about the app upstream such that YunoHost admins can easily obtain further information regarding this app (or, kinda important, try the upstream's demo before deciding to install it).
@ -67,7 +67,7 @@ userdoc = ...
- (optional) `userdoc` (`url`) : the url of the *upstream* project's user documentation, which may help YunoHost end-users with effectively using the app. - (optional) `userdoc` (`url`) : the url of the *upstream* project's user documentation, which may help YunoHost end-users with effectively using the app.
- (optional) `cpe` (`str`) corresponds to the [Common Platform Enumerations code in NIST db](https://nvd.nist.gov/products/cpe). For example for Wekan this is `cpe:2.3:a:wekan_project:wekan`. Not really used at the moment, but may be used in the future to check for known vulnerabilities (CVE) in the app catalog. - (optional) `cpe` (`str`) corresponds to the [Common Platform Enumerations code in NIST db](https://nvd.nist.gov/products/cpe). For example for Wekan this is `cpe:2.3:a:wekan_project:wekan`. Not really used at the moment, but may be used in the future to check for known vulnerabilities (CVE) in the app catalog.
# Integration section ## Integration section
This section is meant to contain info related to the relation between the app and YunoHost, or things like typical resource usage. This section is meant to contain info related to the relation between the app and YunoHost, or things like typical resource usage.
@ -93,7 +93,7 @@ ram.runtime = "1M"
- `ram.runtime` (size) : an *estimate* minimum ram requirement when the app is active and running. For example: 50M, 400M, 1G, ... - `ram.runtime` (size) : an *estimate* minimum ram requirement when the app is active and running. For example: 50M, 400M, 1G, ...
# Install questions ## Install questions
This section contains questions that should be asked to the admin prior to starting the actual install This section contains questions that should be asked to the admin prior to starting the actual install
@ -144,7 +144,7 @@ The full list of question types is : `string`, `text`, `select`, `tags`, `email`
`password`-type questions have special behavior and are NOT automatically saved as setting (user-chosen password should ideally not be stored, at least not hashed...) `password`-type questions have special behavior and are NOT automatically saved as setting (user-chosen password should ideally not be stored, at least not hashed...)
# Resource system ## Resource system
The resource section corresponds to recurring app needs that are to be provisioned/deprovisioned by the core of YunoHost. They include for example: system user, apt dependencies, install dir, data dir, port, permissions, SQL database... Each resource is to be provisioned *before* running the install script, deprovisioned *after* the remove script, and automatically upgraded if needed before running the upgrade script (or provisionned if introduced in the new app version, or deprovisioned if removed w.r.t. the previous app version) The resource section corresponds to recurring app needs that are to be provisioned/deprovisioned by the core of YunoHost. They include for example: system user, apt dependencies, install dir, data dir, port, permissions, SQL database... Each resource is to be provisioned *before* running the install script, deprovisioned *after* the remove script, and automatically upgraded if needed before running the upgrade script (or provisionned if introduced in the new app version, or deprovisioned if removed w.r.t. the previous app version)
@ -167,6 +167,4 @@ In this example:
- `permissions`: an SSOwat `$app.main` permission will be initialized such that the SSO allows access to the app's endpoint according to the chosen `init_main_permission` question. The `main.url = "/"` is here to tell that the main endpoint is the "root" of the app, that is `https://domain.tld/helloworld/` if the app is installed with `domain=domain.tld` and `path=/helloworld` - `permissions`: an SSOwat `$app.main` permission will be initialized such that the SSO allows access to the app's endpoint according to the chosen `init_main_permission` question. The `main.url = "/"` is here to tell that the main endpoint is the "root" of the app, that is `https://domain.tld/helloworld/` if the app is installed with `domain=domain.tld` and `path=/helloworld`
- `apt`: the packages `nyancat`, `lolcat`, `sl` will be installed with `apt`. These are just dummy apt dependencies to illustrate the syntax. - `apt`: the packages `nyancat`, `lolcat`, `sl` will be installed with `apt`. These are just dummy apt dependencies to illustrate the syntax.
The full documentation on resources is available [here (FIXME!]() The full documentation on resources is available [here](/packaging_apps_resources)

28
pages/06.contribute/10.packaging_apps/20.scripts/scripts.md
View file

@ -60,7 +60,7 @@ ynh_add_nginx_config
Note that the scripts are run with the `set -eu` options (except for the remove script), which means that any failing command or use of non-existing variable will trigger an error and stop the script execution. Note that the scripts are run with the `set -eu` options (except for the remove script), which means that any failing command or use of non-existing variable will trigger an error and stop the script execution.
# Variables available in a script context ## Variables available in a script context
Special variables are automatically defined in the context of a script: Special variables are automatically defined in the context of a script:
@ -69,7 +69,7 @@ Special variables are automatically defined in the context of a script:
- During other scripts, all app settings are also loaded and automatically available. - During other scripts, all app settings are also loaded and automatically available.
- Note that some settings are automatically created/updated by app ressources. For example, the `install_dir` setting will automatically be available too and corresponds to typically `/var/www/$app` - Note that some settings are automatically created/updated by app ressources. For example, the `install_dir` setting will automatically be available too and corresponds to typically `/var/www/$app`
# Setting system ## Setting system
Application often need to store long term information in between scripts triggered by the admin. For this, YunoHost has a key-value store for each application called "setting" and is stored in `/etc/yunohost/apps/$app/settings.yml`. Application often need to store long term information in between scripts triggered by the admin. For this, YunoHost has a key-value store for each application called "setting" and is stored in `/etc/yunohost/apps/$app/settings.yml`.
@ -83,7 +83,7 @@ db_name=$(ynh_app_setting_get --app=$app --key=db_name)
ynh_app_setting_set --app=$app --key=db_name --value=$db_name ynh_app_setting_set --app=$app --key=db_name --value=$db_name
``` ```
# Helper system ## Helper system
We call helpers a set of custom bash function created by the YunoHost project to standardize common operations accross all apps. They are all prefixed with `ynh_`. The full list and documentation of these helpers is available on [this page](/packaging_apps_helpers). Some of these helpers are now partially obsolete as they are now handled by the core via app resources. We call helpers a set of custom bash function created by the YunoHost project to standardize common operations accross all apps. They are all prefixed with `ynh_`. The full list and documentation of these helpers is available on [this page](/packaging_apps_helpers). Some of these helpers are now partially obsolete as they are now handled by the core via app resources.
@ -103,7 +103,7 @@ Here is the list of the major ones:
- `ynh_secure_remove` - `ynh_secure_remove`
- `ynh_backup` / `ynh_restore_file` - `ynh_backup` / `ynh_restore_file`
# Configuration/template system ## Configuration/template system
App scripts will often need to create a bunch of configuration files. App scripts will often need to create a bunch of configuration files.
@ -126,7 +126,7 @@ location __PATH__/ {
``` ```
# App sources ## App sources
App scripts will often need to download the upsteam app sources to be deployed in the install dir, via `ynh_setup_source`. App scripts will often need to download the upsteam app sources to be deployed in the install dir, via `ynh_setup_source`.
@ -144,13 +144,13 @@ SOURCE_EXTRACT=true # (yes,
``` ```
# Common operations (TODO/FIXME) ## Common operations (TODO/FIXME)
### installing/upgrading app sources #### installing/upgrading app sources
### adding configurations #### adding configurations
### adding a systemd service #### adding a systemd service
### curl / automatizing install forms #### curl / automatizing install forms
### classic stuff for nodejs apps #### classic stuff for nodejs apps
### classic stuff for php apps #### classic stuff for php apps
### classic stuff for python apps #### classic stuff for python apps
### classic stuff for ??? apps #### classic stuff for ??? apps

6
pages/06.contribute/10.packaging_apps/30.doc/doc.md
View file

@ -9,7 +9,7 @@ routes:
Properly documenting your app is important for user experience ;). YunoHost provides several mechanism to display information to users. Properly documenting your app is important for user experience ;). YunoHost provides several mechanism to display information to users.
# Extensive description : `doc/DESCRIPTION.md` and `doc/screenshots/` ## Extensive description : `doc/DESCRIPTION.md` and `doc/screenshots/`
You are encouraged to add a `doc/DESCRIPTION.md` which should contain a more extensive description than the short description contained in `manifest.toml`. This usually corresponds to listing the key features of the app. You are encouraged to add a `doc/DESCRIPTION.md` which should contain a more extensive description than the short description contained in `manifest.toml`. This usually corresponds to listing the key features of the app.
@ -21,7 +21,7 @@ You can also add translated versions of the `.md` file in, for example, `doc/DES
If your app repository is part of the YunoHost-Apps org, the provided description will be used to auto-regenerate the README.md of your github repo via `yunohost-bot`. If your app repository is part of the YunoHost-Apps org, the provided description will be used to auto-regenerate the README.md of your github repo via `yunohost-bot`.
# Specific notes for admins : `doc/ADMIN.md`, `doc/<whatever>.md` ## Specific notes for admins : `doc/ADMIN.md`, `doc/<whatever>.md`
Sometimes, you may want to ship YunoHost-specific notes regarding the administration of this app. For example, integrating OnlyOffice inside Nextcloud. Sometimes, you may want to ship YunoHost-specific notes regarding the administration of this app. For example, integrating OnlyOffice inside Nextcloud.
@ -31,7 +31,7 @@ Note that you can even use the `__FOOBAR__` syntax which will automatically be r
These notes will be available in the app info page in the webadmin after the app installation. These notes will be available in the app info page in the webadmin after the app installation.
# Pre/post-install notes, pre/post-upgrade notes ## Pre/post-install notes, pre/post-upgrade notes
Sometimes, you may want to display important information to the admin at key points in the app's life cycle. You can do so by providing special markdown files: Sometimes, you may want to display important information to the admin at key points in the app's life cycle. You can do so by providing special markdown files:
- `doc/PRE_INSTALL.md`: displayed right before the installation (for example to warn that « This app install is expected to take around 30 minutes, be patient! » or « This app will automatically add 1GB swap to your system ») - `doc/PRE_INSTALL.md`: displayed right before the installation (for example to warn that « This app install is expected to take around 30 minutes, be patient! » or « This app will automatically add 1GB swap to your system »)

10
pages/06.contribute/10.packaging_apps/40.testing/testing.md
View file

@ -11,13 +11,13 @@ Once you're done writing you app package, you'll want to check that everything w
The YunoHost maintains several tools to automatically and somewhat "objectively" analyze and tests our 400+ apps catalog. The YunoHost maintains several tools to automatically and somewhat "objectively" analyze and tests our 400+ apps catalog.
# Package linter ## Package linter
The [package linter](https://github.com/YunoHost/package_linter) performs a static analysis of your app to check a bunch of recommended practice. The [package linter](https://github.com/YunoHost/package_linter) performs a static analysis of your app to check a bunch of recommended practice.
It is pretty straightforward to run considering that you should only need Python installed. It is pretty straightforward to run considering that you should only need Python installed.
# Package check ## Package check
[Package check](https://github.com/YunoHost/package_check) is a more elaborate software that will tests many scenarios for you app such as: [Package check](https://github.com/YunoHost/package_check) is a more elaborate software that will tests many scenarios for you app such as:
- installing, removing and reinstalling your app + validating that the app can indeed be accessed on its URL endpoint (with no 404/502 error) - installing, removing and reinstalling your app + validating that the app can indeed be accessed on its URL endpoint (with no 404/502 error)
@ -34,13 +34,13 @@ Package check will then summarize the results and compute a quality level rangin
To run its tests, package check uses a LXC container to manipulate the package in a clean environment without any previous installations. Installing LXC/LXD is unfortunately not that straighforward (it kinda depends on your OS/distribution), though we documented how to do so [in the README](https://github.com/YunoHost/package_check#deploying-package_check). To run its tests, package check uses a LXC container to manipulate the package in a clean environment without any previous installations. Installing LXC/LXD is unfortunately not that straighforward (it kinda depends on your OS/distribution), though we documented how to do so [in the README](https://github.com/YunoHost/package_check#deploying-package_check).
## Package check's `tests.toml` ### Package check's `tests.toml`
Package check interfaces with your app's `tests.toml` which allows to control a few things about which tests are run - though it is usually pretty empty as many things can be deduced from the app's manifest. Package check interfaces with your app's `tests.toml` which allows to control a few things about which tests are run - though it is usually pretty empty as many things can be deduced from the app's manifest.
More info about the syntax here are also available [in the README](https://github.com/YunoHost/package_check#teststoml-syntax) More info about the syntax here are also available [in the README](https://github.com/YunoHost/package_check#teststoml-syntax)
# Continous integration (CI) ## Continous integration (CI)
The YunoHost project also developed an interface called [`yunorunner`](https://github.com/YunoHost/yunorunner) which interfaces with `package_check`, handles a job queue, and automatically add jobs to the queue using some triggers. The YunoHost project also developed an interface called [`yunorunner`](https://github.com/YunoHost/yunorunner) which interfaces with `package_check`, handles a job queue, and automatically add jobs to the queue using some triggers.
@ -51,7 +51,7 @@ The two major ones are:
Members of the YunoHost-Apps organization can trigger jobs on the dev CI directly from a pull request simply by commenting something like `!testme` (cf for example [here](https://github.com/YunoHost-Apps/nextcloud_ynh/pull/532#issuecomment-1402751409)). A .png summary of the tests will be automatically displayed once the job completes (and you can click the link to see the entire job execution and debug it). Members of the YunoHost-Apps organization can trigger jobs on the dev CI directly from a pull request simply by commenting something like `!testme` (cf for example [here](https://github.com/YunoHost-Apps/nextcloud_ynh/pull/532#issuecomment-1402751409)). A .png summary of the tests will be automatically displayed once the job completes (and you can click the link to see the entire job execution and debug it).
### Why create `package_check` + `yunorunner` rather than using well-known solutions like Gitlab-CI ? #### Why create `package_check` + `yunorunner` rather than using well-known solutions like Gitlab-CI ?
Constrain 1 : Gitlab-CI or other similar solutions are mostly based around Docker, while we use LXC. In particular, we do want to reuse LXC snapshots of successful install during other tests (upgrade, backup/restore, ..) rather than reinstalling the app from scratch everytime, which drastically reduces the test time. We could do so using Gitlab artifacts, but such artifacts are automatically made public which is not convenient because they contain a full filesystem and their only use it to speed up the test process. Moreover, in the Gitlab-CI paradigm, jobs are not running on the same machine and they would need to download the snapshot which can be lengthy. The other mechanism, caching, is explicitly advertised as not reliable in Gitlab's-CI doc. What would be helpful would be some non-public artifact system (see similar discussion [here](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/336)) Constrain 1 : Gitlab-CI or other similar solutions are mostly based around Docker, while we use LXC. In particular, we do want to reuse LXC snapshots of successful install during other tests (upgrade, backup/restore, ..) rather than reinstalling the app from scratch everytime, which drastically reduces the test time. We could do so using Gitlab artifacts, but such artifacts are automatically made public which is not convenient because they contain a full filesystem and their only use it to speed up the test process. Moreover, in the Gitlab-CI paradigm, jobs are not running on the same machine and they would need to download the snapshot which can be lengthy. The other mechanism, caching, is explicitly advertised as not reliable in Gitlab's-CI doc. What would be helpful would be some non-public artifact system (see similar discussion [here](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/336))

10
pages/06.contribute/10.packaging_apps/packaging_apps_intro.md
View file

@ -12,7 +12,7 @@ This documentation is here to provide all the basic concepts and vocabulary need
We will detail what a YunoHost application package is, how it works, how to make your own package and how to find help if you need it. We will detail what a YunoHost application package is, how it works, how to make your own package and how to find help if you need it.
# 1. Packaging philosophy ## 1. Packaging philosophy
The ability to easily install applications from a catalog is a key feature of YunoHost. While you dive in the process of YunoHost application packaging, you should remember these key principles: The ability to easily install applications from a catalog is a key feature of YunoHost. While you dive in the process of YunoHost application packaging, you should remember these key principles:
@ -25,7 +25,7 @@ The ability to easily install applications from a catalog is a key feature of Yu
- Yunohost app packaging is **not just about installing** sources and dependencies: it's also about maintenance (upgrade, backup, ..) and integrating the app in the YunoHost ecosystem (nginx, sso/ldap, fail2ban, application catalog, ui/ux, ...) - Yunohost app packaging is **not just about installing** sources and dependencies: it's also about maintenance (upgrade, backup, ..) and integrating the app in the YunoHost ecosystem (nginx, sso/ldap, fail2ban, application catalog, ui/ux, ...)
# 2. Prerequisites ## 2. Prerequisites
Before diving in, this documentation assumes that: Before diving in, this documentation assumes that:
@ -38,7 +38,7 @@ You are also encouraged to join the [app packaging chatroom](/chat_rooms) to ask
At some point, you will also want to have a dev/test environment, either using [VirtualBox](/packaging_apps_virtualbox) or [LXC/ynh-dev](https://github.com/yunohost/ynh-dev) which is meant for the core but can totally be used for developping apps. You can also setup a dev/test VPS on your favourite hosting provider, or even develop on your prod if you like to live dangerously ;). At some point, you will also want to have a dev/test environment, either using [VirtualBox](/packaging_apps_virtualbox) or [LXC/ynh-dev](https://github.com/yunohost/ynh-dev) which is meant for the core but can totally be used for developping apps. You can also setup a dev/test VPS on your favourite hosting provider, or even develop on your prod if you like to live dangerously ;).
# 3. Notes about the history of YunoHost's app packaging ## 3. Notes about the history of YunoHost's app packaging
Many things in Yunohost, and Yunohost app packaging format, are historical or were designed in an organic fashion. Thus some aspects may legitimately feel old. Many things in Yunohost, and Yunohost app packaging format, are historical or were designed in an organic fashion. Thus some aspects may legitimately feel old.
@ -55,7 +55,7 @@ Nevertheless, even though helpers existed, the inherent structure of apps was ha
However, [**a future v3 format** has yet to come](https://github.com/YunoHost/issues/issues/2136) to further simplify app packaging (such as taking care of nginx/systemd/... configurations, removing the need to manually write remove/backup/restore scripts, etc ...) However, [**a future v3 format** has yet to come](https://github.com/YunoHost/issues/issues/2136) to further simplify app packaging (such as taking care of nginx/systemd/... configurations, removing the need to manually write remove/backup/restore scripts, etc ...)
# 4. General overview of a Yunohost app structure ## 4. General overview of a Yunohost app structure
A YunoHost app consists in a Git repository. We encourage you to have a look at those code repository to get familiar witch app repository structures: A YunoHost app consists in a Git repository. We encourage you to have a look at those code repository to get familiar witch app repository structures:
- the [`helloworld_ynh`](https://github.com/YunoHost-Apps/helloworld_ynh) app - the [`helloworld_ynh`](https://github.com/YunoHost-Apps/helloworld_ynh) app
@ -103,7 +103,7 @@ Roughly speaking, the install itself generally consists of the following operati
7. Application is ready to use ! 7. Application is ready to use !
# 5. Creating your very first YunoHost package ## 5. Creating your very first YunoHost package
Unless you really want to start from scratch or from [`example_ynh`](https://github.com/YunoHost/example_ynh), one common practice is to identify an app similar to the one you're trying to package - typically because it relies on the same technologies - clone the corresponding code repository, and adapt the various files. Unless you really want to start from scratch or from [`example_ynh`](https://github.com/YunoHost/example_ynh), one common practice is to identify an app similar to the one you're trying to package - typically because it relies on the same technologies - clone the corresponding code repository, and adapt the various files.