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 ## 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). 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: To use them, you need to add following lines in the shell scripts:
```bash ```bash
# Source app helpers # 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/> <br/>
#### Moulinette **Following commands are to be replaced (or even deleted) in future YunoHost versions.**
The CLI [moulinette](/moulinette) provides a few tools to make the packager's work easier:
```bash ```bash
sudo yunohost app checkport <port> sudo yunohost app checkport <port>
``` ```
<blockquote> > This helper checks the port and returns an error if the port is already in use.
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.
</blockquote> > Example:
> ```bash
> port=DEFAULT_PORT
> while ! sudo yunohost app checkport $port ; do
> port=$((port+1))
> done
> ```
<br>
```bash ```bash
sudo yunohost app setting <id> <key> [ -v <value> ] sudo yunohost firewall allow [--no-upnp] {TCP,UDP,Both} PORT
``` ```
<blockquote> > Opens the port number `PORT` on the firewall, for TCP, UDP or both.
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). > Automatic port opening via upnp may be disabled on this port using `--no-upnp`
<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>
```bash ```bash
sudo yunohost app checkurl <domain><path> -a <id> sudo yunohost firewall disallow {TCP,UDP,Both} PORT
``` ```
<blockquote> > Closes the port number `PORT` on the firewall for TCP, UDP or both.
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>
```bash ```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 ```bash
sudo yunohost app ssowatconf sudo yunohost app ssowatconf
``` ```
<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.
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>
-->