How to package applications for YunoHost?

This is one of the topics that is not in-depth enough and can’t be explained clearly enough due to apps being too diverse for a general consensus. Overall, the process is actually rather simple. As long as you are willing to go trial-by-error and don’t mind spending some time thinking, most people with enough time can do it.

The main process

The main process to package a simple application, in my opinion, is this:

• Identify how the application works, where are the configuration files and what variables are needed to customize the setup of the application, what dependencies are needed in order have a working instance;
• Setup a manifest file that would allow you to configure as many of the variables as possible to make sure the experience is customizable, define needed dependencies, etc. (always check other packaged apps if you are unsure, but beware that some things may differ due to different helper versions);
• After identifying how the application is installed normally, write an install script to replicate a typical installation process, including setting up the variables given after user input to make sure the config is given the proper information, setting proper permissions for the app, adding the app’s user to a group if needed, add systemd and nginx configs during install, add yunohost service during install / restore and remove it during remove scripts.
• Make sure to define nginx and systemd configuration as well.
• Once you have a working install script and a working instance, make sure to configure remove/backup/restore scripts.

Helpful resources during the process

In the process, there some things that may help you out:

• When building an app, I recommend using the newest helpers (v2.1 at the time of writing). This streamlines your setup and eliminates installation issues in comparison to using sudo. The list of helpers and how they work (including their code) can be found here: https://doc.yunohost.org/en/packaging_apps_helpers_v2.1
• It is also a good idea to consult the docs regarding the manifest and how the scripts are typically executed: https://doc.yunohost.org/en/packaging_apps_resources
• If there are some special procedures that need to be executed at some point of the install, you can use _common.sh to define these processes to have a less cluttered install script as well as less conflicts in case of lengthy or complicated code.
• My recommendation is to always aim for a setup that requires minimal input from you in the long run. That means, if you can clone the original code repo and simply use ynh_replace to edit some of the source code or or echo to set up a config file for the application, there is no need to do anything more complicated than that. This ensures that regardless of how much the source code changes, you only replace what you specifically are looking for.
• This has been said many times on the internet, but packaging an app is probably the best for you when you actually use the app and are interested in it. It may seem difficult, but once you have done it, it’s there to stay, and it’s definitely much easier to maintain than to package.

In general, there are certain variables that are always available during install, such as the following:

• $port – the port that’s provided or auto-selected before install;
• $domain – the domain that the app will be installed on as selected by the admin;
• install variables from manifest – for instance, if you have a part in manifest that defines install.foobar, this variable would be accessible during install as $foobar;

During install, you may store certain variables that would be always known to belong to the app, for instance:

ynh_app_setting_set --app=$app --key=somethingspecial --value="$foobar"

In this case, we set somethingspecial that would be unique to the $app and contain the value $foobar that has been set during install as defined in the manifest.

Things that you shouldn’t worry about

For the most part, you shouldn’t concern yourself with the following:

• Creating a readme is something you don’t have to do. It is typically generated automagically. You can do that yourself using readme-generator from here: https://github.com/YunoHost/apps_tools
• Transferring the app to Yunohost catalog. This is the last step that you would do as you need to have a working app before that, in my opinion.

Testing the app

The laziest way to test your apps is using Yunorunner, which also has a Yunohost package. However, the publicly available instance is only available to apps that have been transferred to the Yunohost-Apps organisation on github. If you are not yet confident in doing so, it is possible to self-host a Yunorunner instance and use your own resources to fully test the application.

Yunorunner uses package_check and package_linter to test the app. Those can also be run without having to depend on Yunorunner. These packages will let you know at what step and what situation the app was not able to install, remove, upgrade and work, which is great when you need to get the full picture.

However, for doing small changes, especially during the initial setup, it is best to have a development environment, like a separate development LXC with Yunohost installed, to quickly test changes and have the ability to always do a quick rollback if needed. This is faster than depending on Yunorunner / package_check in the beginning as for each step they need to set up an LXC image and make snapshots to test different situations. I’d advise to use those in the end when you have a more or less working application that you need to make sure works in all scenarios and stages. However, that does not forbid you from using the same development environment for both Yunorunner and Yunohost, especially if you have the ability to create snapshots. Testing is all about making sure to break the app as many times as possible and eliminate those points of failure.

Closing remarks

This may get updated with time, but at the moment of writing, this is the gist of how the process of working on a package looks like. The most important step is to begin the process.

Don’t forget – always ask and you shall be answered.