diff --git a/docs/appendices/0.6.0-migration-guide.md b/docs/appendices/0.6.0-migration-guide.md
index d5d773577..1d5da27dc 100644
--- a/docs/appendices/0.6.0-migration-guide.md
+++ b/docs/appendices/0.6.0-migration-guide.md
@@ -13,6 +13,12 @@
 
 - You can now configure host -> container proxy port mappings
   - The UI is handled by the [proxy](/dokku/proxy/) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes.
+- Default port mappings
+  - buildpack apps will be set to `http:80:5000` and will also include https:443:5000` if SSL is enabled.
+  - dockerfile apps with explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container.
+    - You may override this behavior with the [`proxy:ports-*` commands](/dokku/proxy/) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command
+    - dockerfile apps without explicitly exposed ports will behave the same as a buildpack app
+  - NOTE: These defaults **are not** automatically changed on subsequent pushes and must be manipulated with the aforementioned commands
 
 ## calling the dokku binary
 
diff --git a/docs/nginx.md b/docs/nginx.md
index 4f739ae3f..d7efc6e56 100644
--- a/docs/nginx.md
+++ b/docs/nginx.md
@@ -224,6 +224,6 @@ See the [HSTS documentation](/dokku/deployment/ssl-configuration/#hsts-header).
 
 See the [ssl documentation](/dokku/deployment/ssl-configuration/).
 
-## Disabling Nginx
+## Disabling Nginx & Proxy port mappings
 
 See the [proxy documentation](/dokku/proxy/).
diff --git a/docs/proxy.md b/docs/proxy.md
index 4f3f2e245..cd5363914 100644
--- a/docs/proxy.md
+++ b/docs/proxy.md
@@ -1,7 +1,6 @@
 # Proxy plugin
 
 > New as of 0.5.0
-> Port handling functionality is new as of 0.6.0
 
 As of dokku 0.5.0, the proxy functionality has been decoupled from the nginx-vhosts plugin into the proxy plugin. In the future this will allow other proxy software (HAproxy for example) to be used instead of nginx.
 
@@ -24,11 +23,11 @@ By default, the deployed docker container running your app's web process will bi
 
 ```shell
 # container bound to docker interface
-root@dokku:~/dokku# docker ps
+$ docker ps
 CONTAINER ID        IMAGE                      COMMAND                CREATED              STATUS              PORTS               NAMES
 1b88d8aec3d1        dokku/node-js-app:latest   "/bin/bash -c '/star   About a minute ago   Up About a minute                       node-js-app.web.1
 
-root@dokku:~/dokku# docker inspect --format '{{ .NetworkSettings.IPAddress }}' node-js-app.web.1
+$ docker inspect --format '{{ .NetworkSettings.IPAddress }}' node-js-app.web.1
 172.17.0.6
 
 # container bound to all interfaces
@@ -36,3 +35,34 @@ root@dokku:/home/dokku# docker ps
 CONTAINER ID        IMAGE                      COMMAND                CREATED              STATUS              PORTS                     NAMES
 d6499edb0edb        dokku/node-js-app:latest   "/bin/bash -c '/star   About a minute ago   Up About a minute   0.0.0.0:49153->5000/tcp   node-js-app.web.1
 ```
+
+> New as of 0.6.0
+## Proxy port mapping
+
+You can now configure host -> container port mappings with the `proxy:ports-*` commands.
+
+```shell
+$ dokku proxy:ports node-js-app
+-----> Port mappings for node-js-app
+-----> scheme             host port                 container port
+http                      80                        5000
+$ curl http://node-js-app.dokku.me
+Hello World!
+$ curl http://node-js-app.dokku.me:8080
+curl: (7) Failed to connect to node-js-app.dokku.me port 8080: Connection refused
+$ dokku proxy:ports-add node-js-app http:8080:5000
+-----> Setting config vars
+       DOKKU_PROXY_PORT_MAP: http:80:5000 http:8080:5000
+-----> Configuring node-js-app.dokku.me...(using built-in template)
+-----> Creating http nginx.conf
+-----> Running nginx-pre-reload
+       Reloading nginx
+$ curl http://node-js-app.dokku.me
+Hello World!
+$ curl http://node-js-app.dokku.me:8080
+Hello World!
+```
+
+By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.
+
+NOTE: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `proxy:ports-*` syntax detailed above.