Merge pull request #831 from progrium/nginx-docs

Nginx docs

docs/application-deployment.md

@@ -85,6 +85,6 @@ This is in particular useful, then you want to deploy to root domain, as
 
 SSH onto the server, then execute:
 
-```bash
+```shell
 dokku delete myapp
 ```

docs/installation.md

@@ -10,7 +10,7 @@ Ubuntu 14.04 x64 x64. Ideally have a domain ready to point to your host. It's de
 
 To install the latest stable version of dokku, you can run the following bootstrapper command:
 
-```bash
+```shell
 wget -qO- https://raw.github.com/progrium/dokku/v0.3.9/bootstrap.sh | sudo DOKKU_TAG=v0.3.9 bash
 ```
 
@@ -28,7 +28,7 @@ That's it!
 
 ### Development via bash script
 
-```bash
+```shell
 wget -qO- https://raw.github.com/progrium/dokku/master/bootstrap.sh | sudo bash
 ```
 
@@ -41,7 +41,7 @@ You may also wish to take a look at the [advanced installation](http://progrium.
 If you plan on developing dokku, the easiest way to install from your own repository is cloning
 the repository and calling the install script. Example:
 
-```bash
+```shell
 git clone https://github.com/yourusername/dokku.git
 cd dokku
 sudo make install
@@ -52,7 +52,7 @@ repositories. The `DOCKER_URL`, `PLUGINHOOK_URL`, `SSHCOMMAND_URL` and `STACK_UR
 environment variables may be set to override the defaults (see the `Makefile` for how these
 apply). Example:
 
-```bash
+```shell
 sudo SSHCOMMAND_URL=https://raw.github.com/yourusername/sshcommand/master/sshcommand make install
 ```
 
@@ -61,7 +61,7 @@ sudo SSHCOMMAND_URL=https://raw.github.com/yourusername/sshcommand/master/sshcom
 The bootstrap script allows the dokku repository URL to be overridden to bootstrap a host from
 your own clone of dokku using the `DOKKU_REPO` environment variable. Example:
 
-```bash
+```shell
 wget https://raw.github.com/progrium/dokku/master/bootstrap.sh
 chmod +x bootstrap.sh
 sudo DOKKU_REPO=https://github.com/yourusername/dokku.git ./bootstrap.sh
@@ -73,7 +73,7 @@ Dokku ships with a pre-built version of the [buildstep](https://github.com/progr
 default. If you want to build your own version you can specify that with an env
 variable.
 
-```bash
+```shell
 git clone https://github.com/progrium/dokku.git
 cd dokku
 sudo BUILD_STACK=true make install
@@ -141,7 +141,7 @@ Deploy using the following StackScript:
 
 * Run the following commands:
 
-    ```bash
+    ```shell
     apt-get update
 
     apt-get install lxc wget bsdtar linux-image-extra-$(uname -r)
@@ -150,6 +150,6 @@ Deploy using the following StackScript:
     ```
 * After this, you can install dokku the default way:
 
-    ```bash
+    ```shell
     wget -qO- https://raw.github.com/progrium/dokku/master/bootstrap.sh | sudo bash
     ```

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 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`.
-dokku config:set myapp NO_VHOST=1
+
+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
 
@@ -65,7 +89,7 @@ The `subdomain` is inferred from the pushed application name, while the `domain`
 
 You can optionally override this in a plugin by implementing the `nginx-hostname` pluginhook. For example, you can reverse the subdomain with the following sample `nginx-hostname` pluginhook:
 
-```bash
+```shell
 #!/usr/bin/env bash
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
@@ -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
+```

docs/plugins.md

@@ -11,7 +11,7 @@ Let's take a quick look at the current dokku nginx plugin that's shipped with do
 
 ## Installing a plugin
 
-```bash
+```shell
 cd /var/lib/dokku/plugins
 git clone <git url>
 dokku plugins-install
@@ -32,7 +32,7 @@ If you create your own plugin:
 
 The below plugin is a dummy `dokku hello` plugin. If your plugin exposes commands, this is a good template for your `commands` file:
 
-```bash
+```shell
 #!/usr/bin/env bash
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 

docs/remote-commands.md

@@ -13,7 +13,7 @@ RequestTTY yes
 
 It's possible to run commands in the environment of the deployed application:
 
-```bash
+```shell
 dokku run node-js-app ls -alh
 dokku run <app> <cmd>
 ```

docs/upgrading.md

@@ -6,7 +6,7 @@ Dokku is in active development. You can update the deployment step and the build
 
 To update the deploy step (this is updated less frequently):
 
-```bash
+```shell
 cd ~/dokku
 git pull origin master
 sudo make install
@@ -16,7 +16,7 @@ Nothing needs to be restarted. Changes will take effect on the next push / deplo
 
 To update the build step:
 
-```bash
+```shell
 git clone https://github.com/progrium/buildstep.git
 cd buildstep
 git pull origin master
@@ -34,7 +34,7 @@ This should be summary of breaking changes between 0.1 and 0.2 version with inst
 
 software-properties-common is now a dependency for plugins. Before running dokku install script, make sure it is installed.
 
-```bash
+```shell
 > sudo apt-get install software-properties-common
 ```