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: stop advertising app.src, recommend the sources resource instead

Browse source
This commit is contained in:
Alexandre Aubin 2023-09-05 23:58:30 +02:00
parent 68f0f4892e
commit 9ca570ef28
4 changed files with 22 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
pages/06.contribute/10.packaging_apps/10.manifest/docs.md
View file

@ -139,10 +139,15 @@ Every install question is not necessarily mandatory (e.g. a question to propose
## 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: downloading the app's sources, creating a system user, installing apt dependencies, creating the install dir, creating the data dir, finding an available internal port, configuring permissions, initializing an 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)
```toml
[resources]
```toml
[resources.sources.main]
url = "https://some.domain/url/where/to/download/the/app/sources.tar.gz"
sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
[resources.system_user]
[resources.install_dir]
@ -155,6 +160,7 @@ The resource section corresponds to recurring app needs that are to be provision
```
In this example:
- `sources.main`: the URL+checksum from which the app sources will be downloaded + validated
- `system_user`: a system (unix) user will be created for this app, using the app id as username.
- `install_dir`: an install dir will be initialized, named `/var/www/$app` by default. Additional `owner` and `group` property allow to change the owner/group and r/w/x permissions on the created folder.
- `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`

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

@ -130,21 +130,19 @@ location __PATH__/ {
## 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 sources were historically defined in `conf/app.src` files containing the URL + checksum of assets to download.
The `ynh_setup_source` is coupled to another conf file, usually `conf/app.src` which describes where to download the sources, how to check integrity, and how to extract the source.
This is now integrated in `manifest.toml` using the `sources` resource, which pre-download the assets prior to entering the install or upgrade scripts. The sources can then be effectively deployed using `ynh_setup_source`.
For example, this is an `app.src` for wordpress:
For example, for YesWiki, the sources are defined in `manifest.toml` using:
```text
SOURCE_URL=https://downloads.wordpress.org/release/wordpress-6.1.1.zip # The url of the sources
SOURCE_SUM=088280b34aebc7331693e729d8e6b05eb8b9998c.... # The sha256 checksum
SOURCE_SUM_PRG=sha256sum
SOURCE_FORMAT=zip # The format is zip
SOURCE_IN_SUBDIR=true # This is wether or not the sources are directly in the install root
SOURCE_EXTRACT=true # (yes, we want to extract the zip)
```toml
[resources.sources.main]
url = "https://github.com/YesWiki/yeswiki/archive/refs/tags/v4.4.0.tar.gz"
sha256 = "5ceb12d225c20de2ba3cb4ce483348ed1a8ad5b1789d4f4f8f89dc4871524007"
```
More infos on the `source` resource in [the resource system documentation](/packaging_apps_resources).
## Common operations (TODO/FIXME)

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

@ -69,6 +69,7 @@ Parmi les fichiers contenus dans un paquet, les plus importants sont les suivant
- le **manifeste de l'application** `manifest.toml` <small>(ou `.json` dans le passé)</small>
- Il peut être considéré comme la carte d'identité de l'application, contenant diverses métadonnées.
- Il contient également les questions posées lors de l'installation de l'application.
- ainsi qu'un ensemble de "ressource" à initialiser, telles que les sources de l'app à télécharger ou les dépendances apt à installer
- **scripts/** contient un ensemble de scripts bash correspondant aux actions exposées dans YunoHost
- `_common.sh`: common variables or custom functions included in other scripts
- `install`/`remove` : la procédure d'installation et de suppression
@ -76,7 +77,6 @@ Parmi les fichiers contenus dans un paquet, les plus importants sont les suivant
- `backup`/`restore` : les procédures de sauvegarde/restauration
- (`change_url`) : changer l'endroit où l'application est installée en termes de son url d'accès web
- **conf/** contient un ensemble de modèles de configuration utilisés lors de l'installation de l'application. Voici quelques exemples de fichiers couramment trouvés :
- `app.src` : contient l'URL et la somme de contrôle pour télécharger les sources de l'application
- `nginx.conf` : le modèle de configuration de NGINX (=serveur web) pour cette application
- `systemd.service` : le modèle de configuration du service systemd pour cette application
- `config.json/yaml/???` : le modèle de configuration de l'application
@ -109,7 +109,9 @@ Grosso modo, l'installation proprement dite se compose généralement des opéra
A moins que vous ne souhaitiez vraiment partir de zéro ou de [`example_ynh`] (https://github.com/YunoHost/example_ynh), une pratique courante consiste à identifier une application similaire à celle que vous essayez d'empaqueter - typiquement parce qu'elle repose sur les mêmes technologies - à cloner le dépôt de code correspondant, et à adapter les différents fichiers.
TODO/FIXME : here we should list a bunch of well-knowh apps for classic technologies
- Applications PHP :
- Applications NodeJS :
- Applications Python :
- ???
- ???

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

@ -69,6 +69,7 @@ Among the file contained in a package, the most important ones are:
- the **app manifest** `manifest.toml` <small>(or `.json` in the past)</small>
- this can be seen as the ID card of the application, containing various metadatas.
- it also contains the questions asked during the installation of the app.
- and a bunch of "resources" to initialize, such as sources to download or apt dependencies to install
- **scripts/** contains a bunch of bash scripts corresponding to actions exposed in YunoHost
- `_common.sh`: common variables or custom functions included in other scripts
- `install`/`remove`: the install and remove procedure
@ -76,7 +77,6 @@ Among the file contained in a package, the most important ones are:
- `backup`/`restore`: the backup/restore procedures
- (`change_url`): changing where the app is installed in terms of web access url
- **conf/** contains a bunch of configuration templates used when installing the app. Here are some example of commonly found files:
- `app.src`: contains the URL and checksum to downlowd the application sources
- `nginx.conf`: the NGINX (=web server) configuration template for this app
- `systemd.service`: the systemd service configuration template for this app
- `config.json/yaml/???`: the app's configuration template
@ -109,6 +109,8 @@ Roughly speaking, the install itself generally consists of the following operati
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.
TODO/FIXME : here we should list a bunch of well-knowh apps for classic technologies
- PHP apps:
- NodeJS apps:
- Python apps: