How Yunohost’s App Packaging Turns a Git Repo into a One‑Click Self‑Hosted Service

The problem: installing self‑hosted apps manually

When you want to run a web application on your own server you typically need to create a system user, configure a virtual host, obtain a TLS certificate, set up a database, and wire the app into an authentication system. Doing this by hand is repeatable, error‑prone, and makes upgrades a chore.

Thesis: Yunohost’s packaging isolates that complexity

Yunohost treats each app as a versioned package that declares its metadata in a manifest.json and provides lifecycle Bash scripts (install, upgrade, backup, restore, remove). The Yunohost core runs these scripts with root privileges, automatically provisions the required system resources, and registers the app in the LDAP directory used by the SSOwat portal for single sign‑on.

Inside the package: manifest and scripts

• manifest.json – contains the app’s id, version, dependencies, required permissions (e.g. admin, user, visitor), and optional multi‑instance flags.
• scripts/ – Bash files that the core executes. Helper libraries (ynh_*) are available but not mandatory, so script quality varies.

During install the core:

1. Creates a dedicated system user (yunohost.app.<appid>).
2. Renders an nginx virtual host from a template, enables Let’s Encrypt via the Yunohost cron job.
3. Initializes a PostgreSQL or MySQL database and a matching user.
4. Adds LDAP groups that map to the permissions declared in the manifest; SSOwat enforces them at the nginx layer with Lua.
5. Copies the app source into /var/www/<appid> and sets appropriate ownership.

Worked example: installing a custom WordPress fork

Assume you have a Yunohost 11+ server with admin access and you maintain a fork of WordPress at https://github.com/yourname/wp-fork. The fork includes a valid Yunohost manifest and the standard script set.

# Run on the Yunohost host, using sudo to gain the needed privileges
sudo yunohost app install https://github.com/yourname/wp-fork

What happens next (you can observe the steps in the terminal output):

• The core clones the repository into a temporary directory, reads manifest.json, and validates the declared permissions.
• A system user yunohost.app.wp-fork is created.
• An nginx config file appears at /etc/nginx/conf.d/<your-domain>.d/wp-fork.conf; a Let’s Encrypt certificate is requested for <your-domain>.
• A MySQL database wp_fork and user wp_fork are generated, credentials stored in /etc/yunohost/apps/wp-fork/settings.yml.
• LDAP groups wp-fork.admin, wp-fork.user, wp-fork.visitor are added; SSOwat will now enforce access via the portal.
• Finally the source is placed under /var/www/wp-fork and the install script is executed (e.g. moving wp-config.php into place).

You can verify the result without relying on any claimed output:

• Check the manifest copy: cat /etc/yunohost/apps/wp-fork/manifest.json
• Confirm the nginx include: grep -r wp-fork /etc/nginx/conf.d/
• List the LDAP group: sudo yunohost user list | grep wp-fork
• Inspect the database: sudo mysql -e "SHOW DATABASES LIKE 'wp_fork';"
• Trigger a backup and inspect the archive:

  sudo yunohost backup create --apps wp-fork
  ls -l /home/yunohost.backup/archives/

Trade‑off: reliance on Bash scripts and root privileges

The packaging model is powerful but places trust in the app’s scripts. Because they run as root, a mistake or malicious intent can compromise the host. The official catalog runs automated linting and installation tests, yet third‑party repositories bypass that gate. Moreover, Bash lacks strong typing; complex database migrations may become fragile if the script does not check return codes carefully. Some maintainers adopt the ynh_* helper library to mitigate this, but usage is inconsistent across the catalog.

What to verify and next steps

After installing an app, always:

1. Run a backup (yunohost backup create --apps <appid>) and confirm the archive contains both a database dump (*.sql) and a tarball of /var/www/<appid>.
2. Test login via the SSOwat portal with a user that belongs to the app’s visitor group; ensure you reach the app’s landing page.
3. Review the script directory (/etc/yunohost/apps/<appid>/scripts/) for obvious safety issues (e.g. rm -rf / patterns) – a quick manual scan is a low‑cost safety net.

If you plan to publish your own app, start from the official template (yunohost app create <id>) and follow the version‑2 manifest schema documented at https://yunohost.org/packaging_apps. Keep the upgrade script idempotent, use the provided helper functions for database changes, and test the install/upgrade cycle in a disposable VM before pushing to a public repository.