Add documentation for configuring the nginx domains and vhosts

docs/nginx.md

@@ -43,15 +43,39 @@ dokku nginx:import-ssl myapp < archive-of-certs.tar
 
 This archive should is expanded via `tar xvf`. It should contain `server.crt` and `server.key`.
 
-## Disabling VHOSTS
+## Customizing the nginx configuration
 
-If desired, it is possible to disable vhosts by setting the `NO_VHOST` environment variable:
+> New as of 0.3.10
 
-```bash
-dokku config:set myapp NO_VHOST=1
+Dokku currently templates out an nginx configuration that is included in the `nginx-vhosts` plugin. If you'd like to provide a custom template for your application, you should copy the existing template - ssl or non-ssl - into your `$DOKKU_ROOT/$APP` directory at the file `nginx.conf.template`.
+
+For instance - assuming defaults - to customize the nginx template in use for the `myapp` application, create a file at `/home/dokku/myapp/nginx.conf.template` with the following contents:
+
+```
+server {
+  listen      [::]:80;
+  listen      80;
+  server_name $NOSSL_SERVER_NAME;
+
+  # set a custom header for requests
+  add_header X-Served-By www-ec2-01;
+
+  location    / {
+    proxy_pass  http://$APP;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade \$http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host \$http_host;
+    proxy_set_header X-Forwarded-Proto \$scheme;
+    proxy_set_header X-Forwarded-For \$remote_addr;
+    proxy_set_header X-Forwarded-Port \$server_port;
+    proxy_set_header X-Request-Start \$msec;
+  }
+  include $DOKKU_ROOT/$APP/nginx.conf.d/*.conf;
+}
 ```
 
-On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable.
+The above is a sample, http configuration that adds an `X-Served-By` header to requests. The template is manually uploaded this template file and **must** it owned by `dokku:dokku`.
 
 ## Customizing hostnames
 
@@ -76,3 +100,39 @@ echo "$NEW_SUBDOMAIN.$VHOST"
 ```
 
 If the `nginx-hostname` has no output, the normal hostname algorithm will be executed.
+
+You can also use the built-in `domains` plugin to handle:
+
+### Disabling VHOSTS
+
+If desired, it is possible to disable vhosts by setting the `NO_VHOST` environment variable:
+
+```shell
+dokku config:set myapp NO_VHOST=1
+```
+
+On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable.
+
+### Domains plugin
+
+> New as of 0.3.10
+
+The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via `nginx:import-ssl`. Be aware that setting `NO_VHOST` will override any custom domains.
+
+Custom domains are also backed up via the built-in `backup` plugin
+
+```shell
+# where `myapp` is the name of your app
+
+# add a domain to an app
+dokku domains:add myapp example.com
+
+# list custom domains for app
+dokku domains myapp
+
+# clear all custom domains for app
+dokku domains:clear myapp
+
+# remove a custom domain from app
+dokku domains:remove myapp example.com
+```