Yunohost Deployment Diagnostics: From Stalled Apps to 502 Errors

1. App Installation Stalls During Dependency Check

When installing an app, Yunohost may freeze at the "checking dependencies" phase. This usually means the operating‑system package required by the app’s manifest is missing.

Condition	Possible Cause	Diagnostic Check
Installation stops at dependency check	Missing system package	yunohost tools diagnose

1. Run the diagnostic tool
   sudo yunohost tools diagnose
   Look for lines like Missing package: php8-zip.
2. Install the missing package
   sudo apt-get install -y php8-zip (replace the package name with what the diagnostic reported).
3. Re‑run the app installation
   sudo yunohost app install owncloud (or the app you were installing).
4. Verify success
   yunohost app list – the app should appear as installed.

Example: Installing owncloud fails with Dependency check failed: missing package php8-zip. Installing php8-zip via apt-get resolves the issue.

Escalation: If the diagnostic tool reports a package that is not available in your OS repositories, consult the app’s manifest.json for version constraints or contact the app developer for a supported package list.

2. Domain Serves 502 Bad Gateway

Yunohost uses Nginx as a reverse proxy. A 502 error indicates that the upstream service (the app) is unreachable or misconfigured.

Condition	Possible Cause	Diagnostic Check
HTTP 502 on domain	Nginx proxy config out of sync	yunohost domain list

1. List registered domains
   yunohost domain list – confirm the domain is present.
2. Remove and re‑add the domain
   sudo yunohost domain remove yourdomain.tld
sudo yunohost domain add yourdomain.tld.
3. Reload Nginx
   sudo systemctl reload nginx (usually handled by Yunohost, but safe to run).
4. Test the domain
   curl -I https://yourdomain.tld – expect 200 OK.

Escalation: If the domain still returns 502 after re‑registration, check the app’s backend service status with systemctl status app-owncloud and review its logs in /var/log/yunohost/apps/owncloud/.

3. Backup Task Reports ‘Permission Denied’

Yunohost performs automated backups to /var/yunohostbackup. A permission error usually means the backup directory is not owned by the yunohost user.

Condition	Possible Cause	Diagnostic Check
Backup fails with permission denied	Incorrect ownership of backup directory	ls -la /var/yunohostbackup

1. Check ownership
   ls -la /var/yunohostbackup – should show yunohost yunohost.
2. Correct ownership
   sudo chown -R yunohost:yunohost /var/yunohostbackup.
3. Re‑run backup
   sudo yunohost backup run.
4. Verify backup integrity
   ls -l /var/yunohostbackup/latest – ensure files exist.

Escalation: If the directory is on an external device (e.g., NFS, SMB), verify that the mount options grant write access to the yunohost user and that the underlying filesystem supports POSIX permissions.

4. SSO Authentication Fails

Yunohost’s Single Sign‑On relies on accurate system time. Clock drift can cause token verification to fail.

Condition	Possible Cause	Diagnostic Check
SSO login returns error or timeout	Clock drift (NTP disabled)	timedatectl status

1. Check time status
   timedatectl status – look for NTP enabled: no.
2. Enable NTP
   sudo timedatectl set-ntp true.
3. Restart SSO service
   sudo systemctl restart yunohost-sso.service.
4. Test SSO login
   Attempt to log in via https://yourdomain.tld/sso.

Escalation: If time remains unsynced after enabling NTP, verify that the host has outbound access to time.nist.gov or another NTP pool. A firewall blocking outbound UDP port 123 will prevent synchronization.

Verification Checklist After Fixes

• Run yunohost tools diagnostics – all checks should now pass.
• Test domain accessibility: curl -I https://yourdomain.tld returns 200 OK.
• Confirm backup success: ls -l /var/yunohostbackup/latest shows recent files.
• Verify SSO login flows without errors.

Limitations & Caveats

• Commands require root or sudo privileges.
• Package names may differ between Debian/Ubuntu and other distributions; adjust accordingly.
• The diagnostic framework is based on Yunohost 4.x; newer releases may have slightly different command paths.
• Always back up configuration files before making bulk changes.

Conclusion

By following the ordered checks and fixes above, you can quickly isolate and resolve the most common deployment pain points in Yunohost. Keep the diagnostic tool handy, verify each step, and you’ll reduce downtime and improve system reliability.