Adding a Custom App to Yunohost with the packages.d System

Why Use the packages.d Structure?

The Yunohost packaging system is a lightweight wrapper around Debian packages that lets you deploy self‑hosted applications with a single command. All application logic lives under /usr/share/yunohost/packages.d/<app_name>, where a set of scripts and metadata describe how the app should be installed, configured, and removed. This approach guarantees that the web server, database, and user accounts are created automatically, and that future updates do not overwrite your custom files.

Creating a Package Skeleton

Start by copying the template from the official repository:

# On the Yunohost host
sudo mkdir -p /usr/share/yunohost/packages.d/myapp
sudo cp -r /usr/share/yunohost/packages.d/hello_world/* /usr/share/yunohost/packages.d/myapp

Rename the placeholder files:

mv /usr/share/yunohost/packages.d/myapp/hello_world /usr/share/yunohost/packages.d/myapp/myapp
mv /usr/share/yunohost/packages.d/myapp/hello_world.conf /usr/share/yunohost/packages.d/myapp/myapp.conf

Now edit myapp.conf to define the app metadata and required scripts.

Defining Dependencies and Scripts

At minimum, a package needs:

• install – runs during yunohost app install
• config – runs when the admin changes settings via the web UI or yunohost app config
• uninstall – cleans up during removal

Example install script for a static site:

#!/usr/bin/env bash
# install for myapp
set -e

# Create the web directory and copy files
mkdir -p /var/www/$appname
cp -r /usr/share/yunohost/packages.d/myapp/www/* /var/www/$appname

# Create the system user (Yunohost will create it automatically, but we ensure it exists)
yunohost user create $appname --comment "myapp user"

# Configure Nginx via the template system
cat > /etc/nginx/sites-available/$appname.conf <<'EOF'
server {
    listen 80;
    server_name $appname.$domain;
    root /var/www/$appname;
    index index.html;
}
EOF
ln -s /etc/nginx/sites-available/$appname.conf /etc/nginx/sites-enabled/$appname.conf
nginx -t && systemctl reload nginx

# Log success
echo "myapp installed successfully" | yunohost log add myapp

Notice the use of $appname and $domain – Yunohost substitutes these automatically when the script runs. The script must be executable (chmod +x install).

Installing and Verifying the App

With the package ready, install it:

# Run as root or with sudo
sudo yunohost app install myapp

During installation you should see log output similar to:

✓ Creating user myapp… OK
✓ Setting up web directory… OK
✓ Configuring Nginx… OK
✓ myapp installed successfully

Verification steps:

1. Open http://myapp.your-domain.tld – you should see the static site.
2. Check the Nginx config: cat /etc/nginx/sites-enabled/myapp.conf should contain the expected server block.
3. Run yunohost app info myapp to confirm the app appears in the admin panel and that the status is installed.
4. Inspect the log file: cat /var/log/yunohost/myapp.log should contain the success message.

Common Mistakes and Limits

• Overwriting files manually – If you edit files under /var/www/myapp directly, future updates may replace them. Use the config script to make persistent changes.
• Missing install permissions – Forgetting chmod +x on the script will cause the install to fail silently.
• Wrong dependency names – The depends field in myapp.conf must match existing Yunohost packages; otherwise the installer will abort.
• Assuming other distributions – The packaging system relies on Debian/Ubuntu tooling (apt, systemd). Porting to RedHat or Alpine requires rewriting the scripts.
• Not using placeholders – Hard‑coding domain names will break when the site is moved to a different Yunohost instance.

When in doubt, consult the official Yunohost developer guide for the latest script conventions and metadata requirements.