Choosing Manual Nginx Configuration vs. Yunohost Helper for Custom Applications

Problem and Takeaway

The question is whether to use Yunohost’s built‑in application helper or create a manual Nginx configuration fragment for a service that needs a non‑standard port or special path routing. The useful takeaway is that manual configuration gives full control but must be placed in the correct include directory and verified after each change.

Constraints and Options

Yunohost’s reverse proxy is built on Nginx. Each installed app provides a configuration file in /etc/nginx/sites-available/ that is included by the main /etc/nginx/nginx.conf. The system can automatically renew SSL certificates for domains that match the app’s mapping.

Two practical paths exist:

• Use the automatic helper that Yunohost creates for standard web apps.
• Write a manual Nginx block for a custom service.

Trade‑off Summary

Choosing the helper is safest for typical web sites because it guarantees SSL renewal and avoids manual file placement. However, it cannot expose a service on a port other than the one the app declares, nor can it add custom location rules that redirect or rate‑limit specific paths. A manual block is required when you need those advanced settings, but you must keep the file inside /etc/nginx/sites-available/ (or a sub‑directory that the main config includes) and run nginx -t before reloading to prevent syntax errors that could block all sites. You might need a manual block to expose an internal tool on a non‑standard port, to add custom headers, or to implement fine‑grained path routing that the helper does not support.

Manual configuration also avoids the risk that the automatic helper will overwrite your custom settings during an app reinstall, because the helper writes its own file in a dedicated directory that you control. However, if you place the file outside the sites-available hierarchy, Yunohost’s update scripts may rewrite nginx.conf and discard your changes, leading to service interruption.

This guide assumes Yunohost 5.x with Nginx 1.24; newer releases keep the same directory layout but may change the include path, so always verify the include directive in /etc/nginx/nginx.conf before editing.

Manual Implementation Steps

1. Identify the service details. Suppose you run a Node.js API listening on 8080 and want it reachable at https://example.org/api. Replace example.org and 8080 with your own values.
2. Create the configuration file. As root (or with sudo), run:

   cat > /etc/nginx/sites-available/custom_api <<'EOF'
   server {
       listen 80;
       server_name example.org;
   
       location /api/ {
           proxy_pass http://127.0.0.1:8080;
           proxy_set_header Host \$host;
           proxy_set_header X-Real-IP \$remote_addr;
       }
   }
   EOF

   Replace example.org and 8080 with your domain and backend port. The location /api/ block maps the desired path to the backend service. Use a plain editor such as nano or vim to avoid hidden characters.
3. Test syntax. Execute:

   nginx -t

   If the output reports “syntax is ok” and “test is successful”, proceed; otherwise correct the indentation or missing braces. Also verify that the file is located in /etc/nginx/sites-available/ so that the main configuration includes it.
4. Allow the port in the firewall. If you use a port other than 80 or 443, run:

   ufw allow 8080/tcp

   to make sure ufw does not block the traffic before it reaches Nginx.
5. Reload Nginx. Run:

   systemctl reload nginx

   or, on Yunohost systems, use the helper command:

   yunohost service restart nginx

   Both commands require root privileges. After reload, you can also issue nginx -s reload if systemd is unavailable.
6. Verify SSL status. Use the Yunohost helper to confirm the domain is recognized:

   yunohost help cert example.org

   A successful result shows that the proxy is aware of the domain and that a certificate is being managed. If the command reports “no certificate”, the domain may not be linked to any app yet.
7. Functional test. From any client, issue:

   curl -I https://example.org/api

   Expect a 200 response and the appropriate headers. If the connection fails, re‑check the location path and the backend port, and inspect the Nginx error log at /var/log/nginx/error.log for clues.

Limitations and Verification

Manual blocks are not automatically regenerated when Yunohost updates an app or the core Nginx configuration, so you must re‑apply the file after a major system upgrade. Additionally, custom ports must be allowed through the ufw firewall; otherwise the request will be blocked before reaching Nginx. To verify that your change survived an update, repeat the nginx -t test and reload. Then run:

yunohost app list

to ensure the domain still appears in the app registry. Finally, confirm the SSL certificate is valid with:

yunohost cert list example.org

If the certificate shows “valid” and the curl test returns 200, the configuration is correctly in place.

After a reload, examine /var/log/nginx/error.log for any warning messages such as “duplicate server name” which indicate conflicting site definitions.

Conclusion

When you need full control over ports, path routing, or custom headers, a manual Nginx fragment placed in the proper include directory is the appropriate choice. For standard web applications, the automatic helper remains the simplest and safest route. Always validate with nginx -t, reload, and test SSL before considering the task complete.