From 6b48b250a7869342ecb7a45cf632afd3ac345626 Mon Sep 17 00:00:00 2001
From: Jose Diaz-Gonzalez <josegonzalez@users.noreply.github.com>
Date: Thu, 7 Apr 2016 21:14:56 -0400
Subject: [PATCH] Add documentation on customizing hostnames

[ci skip]
---
 docs/deployment/domain-configuration.md | 26 +++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/deployment/domain-configuration.md b/docs/deployment/domain-configuration.md
index ea1f2c9ae..8669475bb 100644
--- a/docs/deployment/domain-configuration.md
+++ b/docs/deployment/domain-configuration.md
@@ -12,6 +12,32 @@ domains:remove <app> DOMAIN
 domains:set-global <domain>                                                                  Set global domain name
 ```
 
+## Customizing hostnames
+
+Applications typically have the following structure for their hostname:
+
+```
+scheme://subdomain.domain.tld
+```
+
+The `subdomain` is inferred from the pushed application name, while the `domain.tld` is set during initial configuration and stored in the `$DOKKU_ROOT/VHOST` file. It can then be modified with `dokku domains:set-global`. This value is used as a default TLD for all applications on a host.
+
+If a FQDN such as `other.tld` is used as the application name, the default `$DOKKU_ROOT/VHOST` will be ignored and the resulting vhost URL for that application will be `other.tld`. The exception to this rule being that if the FQDN has the same ending as the default vhost (such as `subdomain.domain.tld`), then the entire FQDN will be treated as a subdomain. The application will therefore be deployed at `subdomain.domain.tld.domain.tld`.
+
+You can optionally override this in a plugin by implementing the `nginx-hostname` plugin trigger. For example, you can reverse the subdomain with the following sample `nginx-hostname` plugin trigger:
+
+```shell
+#!/usr/bin/env bash
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+APP="$1"; SUBDOMAIN="$2"; VHOST="$3"
+
+NEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`
+echo "$NEW_SUBDOMAIN.$VHOST"
+```
+
+If the `nginx-hostname` has no output, the normal hostname algorithm will be executed.
+
 ## Disabling VHOSTS
 
 If desired, it is possible to disable vhosts with the domains plugin.