Installing Apps on Yunohost Without Manual Server Configuration

The problem: repeatable app hosting without manual plumbing

You want to run a self-hosted service—say, a bookmarks manager or a note-taking app—on a Debian server. Without a platform, that usually means installing a web server, configuring PHP or Python, setting up a database, creating a systemd unit, generating nginx virtual hosts, and wiring authentication into your user directory. Do that once and it is tedious; do it for several apps and it is easy to drift between configurations.

Yunohost aims to remove that plumbing with a single command: yunohost app install. The command reads an app manifest, resolves dependencies, and configures nginx, databases, systemd services, and user access automatically. This post explains what actually changes on the system, how to verify the result, and where the approach has limits.

What the install command touches

Yunohost is built for Debian. Official support for other distributions is limited, so this workflow assumes a Debian host. When you install an app, the platform parses a YAML manifest that declares the app's requirements and configuration templates. The manifest maps to system resources rather than relying solely on traditional Debian packages.

The installer typically creates or modifies:

• An nginx site configuration in /etc/nginx/sites-available/ and enables it in /etc/nginx/sites-enabled/.
• A systemd service unit so the app starts on boot and restarts on failure.
• A database and database user, when the app manifest requires one.
• An LDAP-style group or permission entry so Yunohost users can access the app through the portal.
• App-specific state under /etc/yunohost/apps/<app-id>/.

<app-id> is a placeholder for the application's short identifier, such as wallabag or nextcloud.

Worked example: install and verify one app

Run commands directly on the Yunohost host, not from your laptop. You need root privileges, typically through sudo.

sudo yunohost app install <app-id>

Replace <app-id> with an app available in the Yunohost catalog. Before installing, check what is available:

yunohost app list

This command is read-safe and does not change system state. It lists available or installed apps.

After installation, verify what was created:

1. List installed apps: yunohost app list. The new app should appear with its version and status.
2. Inspect the app directory: ls /etc/yunohost/apps/<app-id>/. You should see manifest and configuration files.
3. Check nginx generation: ls /etc/nginx/sites-available/ | grep <app-id> and confirm a matching symlink exists under sites-enabled.
4. Confirm the systemd unit: systemctl status yunohost-app-<app-id> or the unit name declared by the app.

Risk: if another service already uses the app's HTTP port, nginx may fail to reload. If the manifest declares a database version unavailable on your Debian release, dependency resolution can fail mid-installation, leaving partial configuration behind.

Limitations and when to be cautious

The app catalog is smaller than general Linux package repositories, so specialized software may require you to create or maintain a custom app package. Automated installs can also mask dependency conflicts. Two apps that expect different versions of the same library may install cleanly alone but conflict together. Backup and restore operations depend on app definitions being properly versioned; otherwise they can fail silently or restore incomplete state.

Practical check: after installing any app, reload nginx and confirm the app still responds at its expected URL. Do not assume success because the installer returned without an error.

Rolling back and ongoing operation

Because yunohost app install changes system state, the practical rollback is removal:

sudo yunohost app remove <app-id>

This should remove the app's nginx configuration, systemd unit, database, and app directory, though behavior depends on the app manifest. Review the app's documentation before removing production data, because removal may delete databases and uploaded files.

For day-to-day operation, use the Yunohost web administration interface to monitor resource consumption and apply app updates through the platform rather than editing nginx or systemd files by hand.

Bottom line

Use yunohost app install when you want Debian-based self-hosting with automated service configuration and centralized user access. Verify the catalog first, inspect generated nginx and systemd files after installation, and test removal in a non-production environment before relying on it for rollback.