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 pull request #477 from JocelynDelalande/jd-english-helpers-update

Browse source 
[fix] Sync packaging helpers doc french → english
This commit is contained in:
M5oul 2017-04-02 15:58:09 +02:00 committed by GitHub
commit d02c1152ff
1 changed files with 232 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

283
packaging_apps_helpers.md
View file

@ -2,85 +2,264 @@
## Shell helpers
Since YunoHost 2.4 release, **new shell helpers** are available to ease packaging, in particular for common tasks like password generation, MySQL database creation…
Since YunoHost 2.4 release, **new shell helpers** are available to ease common packaging tasks like password generation, MySQL database creation…
Examples are available in the [example application](https://github.com/YunoHost/example_ynh/blob/master/scripts/install). We advise to use them.
Usage examples are available in the [example application](https://github.com/YunoHost/example_ynh/blob/master/scripts/install). We advise to use them.
You can find them on this [repository](https://github.com/YunoHost/yunohost/blob/unstable/data/helpers.d).
To use them, you need to add following lines in the shell scripts:
```bash
# Source app helpers
. /usr/share/yunohost/helpers
source /usr/share/yunohost/helpers
```
<!--
### Available helpers list (non exhaustive)
#### Database
```bash
ynh_mysql_execute_as_root SQL DB
```
> Runs the SQL command `SQL` as database root user on `DB` database (this last argument is optional).
```bash
ynh_mysql_execute_file_as_root FILE DB
```
> Runs the SQL commands listed inside `FILE` as root user on `DB` database (this last argument is optional).
```bash
ynh_mysql_create_db DB USER PWD
```
> Create the `DB` database and grants all rights to `USER` (created on the fly with `PASSWORD` password).
```bash
ynh_mysql_drop_db DB
```
> Delete the `DB` database.
```bash
ynh_mysql_dump_db DB > ./FILE
```
> Exports the `DB` database into the `FILE` file.
#### Debian packages handling
```bash
ynh_package_is_installed PACKAGE
```
> Tests if the Debian package `PACKAGE` is installed on the system.
> Read command output to know the result. e.g:
> ```bash
> if ! ynh_package_is_installed "yunohost" ; then
> echo "Oops, package is not installed"
> else
> echo "Package is installed"
> fi
> ```
```bash
ynh_package_version PACKAGE
```
> Returns the installed version number of `PACKAGE`.
```bash
ynh_package_update
```
> Updates the packages list (`apt update`) in a silent and non-interactive way.
**Be careful, the following commands are to be avoided when possible. Installing (and even more removing) a package without handling conflicts and dependencies is risky. That will be improved in future Yunohost versions.**
```bash
ynh_package_install PACKAGE1 PACKAGE2
```
> Installs (`apt install`) `PACKAGE1`, `PACKAGE2`… packages, in a non interactive and silent way.
```bash
ynh_package_autoremove PACKAGE1 PACKAGE2
```
> Removes (`apt-get autoremove`) `PACKAGE1`, `PACKAGE2`… packages in a silent and non-interactive way.
#### Apps configuration
```bash
ynh_app_setting_set APP KEY VALUE
```
> Store the setting named `KEY` with value `VALUE` for the app `APP`. This allows to reuse it later (typically in the `upgrade` script), or so that YunoHost can autoconfigure the SSO.
> The settings are stored in the /etc/yunohost/apps/${APP}/settings.yml file.
> For example, to store the visibility setting (private or public app), you can use :
> ```bash
> ynh_app_setting_set my_app is_public "yes"
> ```
The SSO uses app stored settings to allow or deny public access to HTTP resources. There are 6 configuration keys :
`skipped_uris`, `unprotected_uris` and `protected_uris` are relative to app path. Example:
> ```bash
> ynh_app_setting_set app_name skipped_uris "/blog"
> ```
> Matches the /blog path of the application: https://domain.tld/path_app/blog and everything under this path, but not https://domain.tld/path_app/.
**skipped_uris**
An URL set with *skipped_uris* key will be totally ignored by the SSO, which means that the access will be public and the logged-in user information will not be passed to the app.
**unprotected_uris**
An URL set with *unprotected_uris* key will be accessible publicly, but if an user is logged in, his information will be accessible (though HTTP headers) to the app.
**protected_uris**
An URL set with *protected_uris* will be blocked by the SSO and accessible only to authenticated and authorized users.
`skipped_regex`, `unprotected_uris` and `protected_regex` are regex counterparts of the above keys.
> The syntax is **not** the "standard" regex syntax ([PCRE](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions)) but [Lua patterns](http://lua-users.org/wiki/PatternsTutorial).
The regex patterns match the whole URL, unlike the string patterns (which match only the app-local part of the URL, as detailed above). This means you must write complete patterns including the *domain* and *path*.
> For example, to use *skipped_regex* to match /blog followed by a 1+ digit number:
> ```bash
> ynh_app_setting_set app_name skipped_regex "$domain$path/blog%?%d+$"
> ```
> This may lead to an issue : if $domain or $path contain a dash (-), it will interpreted as a pattern magic char. That is why dashes must be escaped with a %.
> ```bash
> domainregex=$(echo "$domain" | sed 's/-/\%&/g')
> pathregex=$(echo "$path" | sed 's/-/\%&/g')
> ynh_app_setting_set app_name skipped_regex "$domainregex$pathregex/blog%?%d+$"
> ```
```bash
ynh_app_setting_get APP KEY
```
> Get the value of the setting named `KEY` for the `APP` app.
> Example :
> ```bash
> is_public=$(ynh_app_setting_get app_name is_public)
> ```
```bash
ynh_app_setting_delete APP KEY
```
Delete the setting named `KEY` for the `APP` app.
#### Users management
```bash
ynh_user_exists USERNAME
```
> Checks the existence of `USERNAME` user in YunoHost.
> Command return code must be checked to know the result.
> Example:
> ```bash
> if ynh_user_exists "johndoe" ; then
> echo "This user exists!"
> fi
> ```
```bash
ynh_user_get_info USERNAME KEY
```
> Get the `KEY` information on `USERNAME` user.
> Possible `KEY` values are:
> - firstname
> - fullname
> - lastname
> - mail
> - mail-aliases
> - mailbox-quota
> Example:
> ```bash
> mailadmin=$(ynh_user_get_info $admin mail)
> ```
```bash
ynh_system_user_exists USERNAME
```
> Checks if the `USERNAME` unix user exists.
> Command return code must be checked to know the result.
> Example:
> ```bash
> if ynh_system_user_exists "www-data" ; then
> echo "User exists on system!"
> fi
> ```
#### Other commands
```bash
ynh_string_random LENGTH
```
> Generates a random string of `LENGTH` chars (defaults to 24).
```bash
ynh_die MSG RETCODE
```
> Displays the `MSG` message on stderr and exits the script with `RETCODE` return code (defaults to 1).
<br/>
#### Moulinette
The CLI [moulinette](/moulinette) provides a few tools to make the packager's work easier:
**Following commands are to be replaced (or even deleted) in future YunoHost versions.**
```bash
sudo yunohost app checkport <port>
```
<blockquote>
This helper checks the port and returns an error if the port is already in use.
</blockquote>
> This helper checks the port and returns an error if the port is already in use.
> Command return code must be checked to know the result.
> Example:
> ```bash
> port=DEFAULT_PORT
> while ! sudo yunohost app checkport $port ; do
> port=$((port+1))
> done
> ```
<br>
```bash
sudo yunohost app setting <id> <key> [ -v <value> ]
sudo yunohost firewall allow [--no-upnp] {TCP,UDP,Both} PORT
```
<blockquote>
This is the most important helper of YunoHost. It allows you to store some settings for a specific app, in order to be either reused afterward or used for YunoHost configuration (**e.g.** for the SSO).
<br><br>
It sets the value if you append ```-v <value>```, and gets it otherwise.
<br><br>
** Some useful settings **<br><br>
```skipped_uris```<br><br>
Remove the protection on the uris list provided separated by commas.<br><br>
```protected_uris```<br><br>
Protects the uris list provided separated by commas. Only logged in users will have access.<br><br>
There are also `skipped_regex`, `protected_regex`, `unprotected_uris`, `unprotected_regex`.<br><br>
**Be careful** : you must run `yunohost app ssowatconf` to apply the effect. URIs will be converted into URLs and written to the file /etc/ssowat/conf.json.<br><br>
Example:<br>
```yunohost app setting myapp unprotected_urls -v "/"```<br>
```yunohost app ssowatconf```<br>
These commands will disable the SSO on the root of the aplication like domain.tld/myapp This is useful for public application.
</blockquote>
<br>
> Opens the port number `PORT` on the firewall, for TCP, UDP or both.
> Automatic port opening via upnp may be disabled on this port using `--no-upnp`
```bash
sudo yunohost app checkurl <domain><path> -a <id>
sudo yunohost firewall disallow {TCP,UDP,Both} PORT
```
<blockquote>
This helper is useful for web apps and allows you to be sure that the web path is not taken by another app. If not, it "reserves" the path.
<br><br>
**Note**: do not prepend `http://` or `https://` to the `<domain><path>`.
</blockquote>
<br>
> Closes the port number `PORT` on the firewall for TCP, UDP or both.
```bash
sudo yunohost app initdb <db_user> [ -p <db_pwd> ] [ -s <SQL_file> ]
sudo yunohost app checkurl DOMAINPATH -a APP
```
<blockquote>
This helper creates a MySQL database. If you do not append a password, it generates one and returns it. If you append a SQL file, it initializes your database with the SQL statements inside.
</blockquote>
<br>
> Checks `DOMAIN`/`PATH` url availability. Useful for web apps to make sure the chosen URL is not already taken by another app. If the URL is available, that commands register for the `APP` application.
> **Note**: do not prepend `http://` or `https://` to `DOMAINPATH`.
```bash
sudo yunohost app addaccess [--users=USER] APP
```
> Allow the `USER` user to access `APP`.
```bash
sudo yunohost app removeaccess --users=USER APP
```
> Remove the access authorization to `APP` from `USER` user.
```bash
sudo yunohost service remove NAME
```
> Remove the service `NAME` from the YunoHost management interface.
```bash
sudo yunohost app ssowatconf
```
<blockquote>
This helper reloads the SSO configuration. You have to call it at the end of the script when you are packaging a web app.
</blockquote>
-->
> This commands rebuilds the SSO configuration. It is called automatically at the end of any script, but you may want to call it by hand before.