Over the length of time I've been using and contributing to dokku, the nginx functionality and implementation complexity of said functionality has increased significantly. It doesn't seem (to me at least) that we have documented fully what the plugin is meant to do, what cases are automated, and what cases are left to the reader to implement with a custom template.

My personal position on this (and with software development in general, I think) is we should do a handful of things very very well and document the edge cases to give users the ability to implement them in their own way. (read: batteries included but replaceable)

This issue is an attempt to document and clarify what this plugin does and subsequently clean up the implementation to this end. I will enumerate my current understanding of this and willfully open the conversation to the community in hopes to solidify the expectation of functionality, and subsequently help prevent the historic regression cycle we've seen in this plugin.

Current expected behaviors to be automated

baseline assumptions

• nginx listener on port 80
  • no-ssl
  • Loadbalancer (LB) with SSL termination. not sure how this differs from no-ssl given our current templates
• nginx listener on port 443 (ssl hosted on box with 301 redirection from port 80)
• some list of domains (server_name args) for which to answer
• custom nginx template may override any of the aforementioned scenarios using documented template variables
• dokku will validate (nginx -t) all nginx config before successfully deploying an app if VHOST support is enabled for said app

VHOST/domain support

• local ssl configurations (i.e. non-ssl-terminated LBs) require nginx but not a domain (i.e. self-signed certs for development or internal services perhaps)
• non-ssl configurations do not require a domain or nginx
• VHOST support is on by default but can be disabled both explicitly or implicitly
  • (explicit) NO_VHOST env variable
    • nginx listens on random high port
    • container listens on external interface
  • (implicit) if either $DOKKU_ROOT/VHOST or $DOKKU_ROOT/HOSTNAME contain IPv4/IPv6 addresses, NO_VHOST is set for the deployed app
• nginx can be disabled completely
  • removes the app-specific nginx config and restart a container that listens on a random high port on the external interface of the host
• app-specific domains/VHOST support ($DOKKU_ROOT/VHOST) works even without a global VHOST ($DOKKU_ROOT/VHOST)
• all domains added with the domains plugin can be used to access the app
• default domain is <appname>.$(cat $DOKKU_ROOT/HOSTNAME), if...
  • $DOKKU_ROOT/$APP/VHOST doesn't exist
  • $DOKKU_ROOT/VHOST and $DOKKU_ROOT/HOSTNAME do not contain IPv4 or IPv6 addresses
  • $DOKKU_ROOT/VHOST exists
  • nginx-hostname plugin trigger returns nothing

ssl specifics

• server-wide AND app-specific SSL certificates are supported
  • app-specifc certs take precedence over server-wide certs
• SSL certs with SANs are supported
• nginx will proxy the same app on all SSL domains (as found in the defined cert) and any additional non-SSL domains added with the domains plugin (without redirection)

I may have missed some cases but I think this illustrates how insane we've allowed our nginx support to become and I hope we can come to consensus on a more restrained scope of functionality or a more rational implementation. Now go ahead, talk amongst ya'selves.

refs: #1625 #1581 #1597 #1575 #674
those are just the open issues regarding nginx config.