doc/packaging_apps.md

App packaging

The purpose of this document is to teach you how to package an application for YunoHost.

Requirements

To package an application, here are the requirements:

• An account on a git server (e.g. GitHub) to publish the application;
• Basic knowledge of git, bash shell and other programming stuff;
• A testing virtual machine or a distant server, or a development environement, ynh-dev or VirtualBox, to package and test the package.

Content

A YunoHost package is composed of:

• A manifest.json file
• A scripts directory, which contains five Shell scripts: install, remove, upgrade, backup and restore
• Optional directories, containing sources or conf files
• A LICENSE file containing the license of the package
• A presentation page of your package in a README.md file

 A basic package feel free to use it as a framework.

Manifest

Manifest

Scripts

Scripts

Architecture and arguments

Since YunoHost has a unified architecture, you will be able to guess most of the settings you need. But if you need variable ones, like the domain or web path, you will have to ask the administrator at installation (see arguments section in the manifest above).

Arguments management

Nginx configuration

Nginx configuration

Multi-instance

Multi-instance

Hooks

YunoHost provides a hook system, which is accessible via the packager's script callbacks in command line. The scripts have to be placed in the hooks repository at the root of the YunoHost package, and must be named priority-hook_name, for example: hooks/50-post_user_create will be executed after each user creation.

Note: priority is optional, default is 50.

Take a look at the Nextcloud package for a working example.

Helpers

Helpers

Registering a log file

In a lot of case, you might want to register a log file created by your app, to make it available in the webadmin. To register a log, you can create a reference file /var/log/yunohost/categories/app/APPNAME.yml.

You can specify a start date by starting the file name with the date formatted as YYYYMMDD-HHMMSS.

Example of yml metadata log file:

log_path: /path/to/your/log/file.log

If you want display some context info, you can add:

extra:
  env:
    args1: value1
    args2: value2
    args3: value3

You can attach the log to an app, domain, service or user like this :

related_to:
    - ['app', 'APPNAME']
    - ['service', 'SERVICE1']
    - ['service', 'SERVICE2']
    - ['domain', 'DOMAIN.TLD']

This will be used to filter logs and display all log related to an entity like a user, a domain, an app or a service.

Test it!

In order to test your package, you can execute your script standalone as admin (do not forget to append required arguments):

su - admin -c "/bin/bash /path/to/my/script my_arg1 my_arg2"

Or you can use command line:

yunohost app install /path/to/my/app/package

Note that it also works with a Git URL:

yunohost app install https://github.com/author/my_app_package.git

Packaging best practices

Here is a list of best practices for application install scripts:

• scripts should use sudo cp -a ../sources/. $final_path instead of sudo cp -a ../sources/* $final_path;
• install script must contain support in case of script errors to delete residuals files thanks to set -e and trap;
• install script should use the command-line method instead of calls to curl through web install form;
• install script should save install answers;
• application sources should be checked with a control sum (sha256, sha1 or md5) or a PGP signature;
• scripts should be tested on Debian Stretch 32 bits, 64 bits and ARM architectures;
• backup and restore scripts should be present and functional.

To be define the quality of a package, it'll obtained a level, determined according to somes criteria of installation and according to respect to package guidelines.

Package script checker

Package checker

This Python script checks:

• that the package is up to date wich last specifications
• that all files are present
• that the manifest doesn't have syntax errors
• that scripts exit well before modifing the system during verification.

Publish and ask for testing your application

• Publishing a post on the Forum with the App integration category, to ask for testing and feedback on your application.

• Ask your application to be added to the app repository to be displayed in the non-official apps list. Specify its progress state: notworking, inprogress, or working.

• Subscribe to the Apps mailing list to be informed about packaging evolution.

Officalization of an application

To become an official application, it must be tested well enough, be stable and should work on Debian Stretch 64 bits, 32 bits and ARM architectures. If you think those conditions are met, ask for official integration of your application.