Yunohost's packages.d: How the packaging system automates self-hosted app deployment

The Challenge of Self-Hosting

Every time you want to run a new service on your server, you face the same cascade of decisions: Which ports to open? How to configure the database? What SSL certificate should protect it? YunoHost tackles this by treating each application as a first-class package with its own lifecycle management.

How YunoHost's Packaging System Works

YunoHost's packages.d directory contains metadata files that define how applications are installed, upgraded, and removed. Each package specifies dependencies, configuration templates, and the exact scripts that handle setup tasks. When you run yunohost app install, the system reads these definitions and executes the appropriate install script automatically.

The Package Metadata Structure

A typical package definition includes:

• install - Sets up the service, creates databases, configures users
• upgrade - Migrates configurations and data when the app updates
• remove - Cleans up files, databases, and configuration entries
• manifest.json - Declares dependencies, ports, and configuration options

Seeing It in Action: Installing Kanboard

Let's examine what happens when you install Kanboard, a lightweight project management tool. First, check what packages are available:

ls /usr/share/yunohost/packages.d/

Run this on your YunoHost server as root or with sudo privileges. You should see directories for various applications, each containing their manifest and script files.

The install script for Kanboard would typically:

1. Create a dedicated system user for the application
2. Set up a SQLite database file with proper permissions
3. Configure the web server to proxy requests to the correct port
4. Generate SSL certificates through Let's Encrypt integration
5. Update DNS records if using YunoHost's DNS management

To actually install it, you would run:

yunohost app install kanboard

This single command orchestrates all the complexity behind the scenes. Check the application list in the admin panel afterward to verify the installation succeeded.

Trade-offs and Limitations

While this automation is powerful, it comes with trade-offs. Custom modifications to application files may be overwritten during package upgrades since the install scripts regenerate configurations from templates. Additionally, the packaging abstraction can hide underlying system errors, making deep debugging more challenging for users who need to understand what's happening at the OS level.

Dependency conflicts are another consideration. If you manually upgrade the underlying Debian version outside of YunoHost's supported release cycle, you might encounter compatibility issues that the packaging system wasn't designed to handle.

Practical Verification Steps

To verify your package system is working correctly:

1. Inspect the package directory: ls -la /usr/share/yunohost/packages.d/
2. Check a specific app's manifest: cat /usr/share/yunohost/packages.d/kanboard/manifest.json
3. Review install logs after deployment: cat /var/log/yunohost/app_install.log

The key takeaway: YunoHost's packages.d system transforms complex deployment procedures into repeatable, manageable operations. By understanding how these packages work, you can confidently deploy and maintain self-hosted services while being aware of the trade-offs involved in this abstraction layer.