Add specific documentation around user management. Closes #1978

- Briefly cover sshcommand internals
- Show several examples for using sshcommand
- Split out docs onto a new page and relink to it where necessary
- Refer to user-auth plugin trigger for scoping commands to specific users.

[ci skip]

docs/advanced-installation.md

@@ -48,13 +48,7 @@ Once dokku is installed, if you are not using the web-installer, you'll want to
 
 Set up a domain and a wildcard domain pointing to that host. Make sure `/home/dokku/VHOST` is set to this domain. By default it's set to whatever hostname the host has. This file is only created if the hostname can be resolved by dig (`dig +short $(hostname -f)`). Otherwise you have to create the file manually and set it to your preferred domain. If this file still is not present when you push your app, dokku will publish the app with a port number (i.e. `http://example.com:49154` - note the missing subdomain).
 
-You'll have to add a public key associated with a username by doing something like this from your local machine:
-
-    $ cat ~/.ssh/id_rsa.pub | ssh dokku.me "sudo sshcommand acl-add dokku $USER"
-
-If you are using the vagrant installation, you can use the following command to add your public key to dokku:
-
-    $ cat ~/.ssh/id_rsa.pub | make vagrant-acl-add
+Follow the [user management documentation](/dokku/deployment/user-management) in order to add users to dokku.
 
 That's it!
 

docs/application-deployment.md

@@ -120,17 +120,6 @@ dokku apps:rename OLD_NAME NEW_NAME
 
 This will copy all of your app's contents into a new app directory with the name of your choice, delete your old app, then rebuild the new version of the app and deploy it. All of your config variables, including database urls, will be preserved.
 
-### Adding deploy users
-
-While it is possible to use password-based authorization to push to Dokku, it is preferable to use key-based authentication for security. You can add your public key to the dokku user's `authorized_keys` file with the following command:
-
-```shell
-# from your local machine
-# replace dokku.me with your domain name or the host's IP
-# replace root with your server's root user
-cat ~/.ssh/id_rsa.pub | ssh root@dokku.com "sudo sshcommand acl-add dokku [description]"
-```
-
 ### Deploying non-master branch
 
 Dokku only supports deploying from its master branch, so if you'd like to deploy a different local branch use: ```git push dokku <local branch>:master```
@@ -195,9 +184,9 @@ This is in particular useful, then you want to deploy to root domain, as
 
 Dokku is, at its core, a docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the docker daemon. One thing to note as in [issue #1220](https://github.com/dokku/dokku/issues/1220), dokku executes a cleanup function prior to every deployment. This function removes all exited containers and all 'unattached' images.
 
-### Specifying a custom buildpack
+### Adding deploy users
 
-See the [buildpack documentation](/dokku/deployment/buildpacks/).
+See the [user management documentation](/dokku/deployment/user-management).
 
 ## Default vhost
 
@@ -207,10 +196,14 @@ See the [nginx documentation](/dokku/nginx/#default-site).
 
 See the [dockerfile documentation](/dokku/deployment/dockerfiles/).
 
-## Zero downtime deploy
+### Specifying a custom buildpack
 
-See the [zero-downtime deploy documentation](/dokku/checks-examples/).
+See the [buildpack documentation](/dokku/deployment/buildpacks/).
 
 ## Image tagging
 
 See the [image tagging documentation](/dokku/deployment/images).
+
+## Zero downtime deploy
+
+See the [zero-downtime deploy documentation](/dokku/checks-examples/).

docs/deployment/user-management.md

@@ -0,0 +1,48 @@
+# User Management
+
+While it is possible to use password-based authorization to push to Dokku, it is preferable to use key-based authentication for security.
+
+Users in dokku are managed via the `~/dokku/.ssh/authorized_keys` file. While you *can* manually edit this file, it is **highly** recommended that you follow the below steps to manage users on a dokku server.
+
+## SSHCommand
+
+Dokku uses the [`sshcommand`](https://github.com/dokku/sshcommand) utility to manage ssh keys for the dokku user. The following is the usage output for sshcommand.
+
+```
+sshcommand create <user> <command>              # creates a user forced to run command when SSH connects
+sshcommand acl-add <user> <ssh-key-name>        # adds named SSH key to user from STDIN
+sshcommand acl-remove <user> <ssh-key-name>     # removes SSH key by name
+sshcommand help                                 # displays the usage help message
+```
+
+In dokku's case, the `<user>` section is *always* `dokku`, as this is the system user that the dokku binary performs all it's actions. Keys are given unique names, which can be used in conjunction with the [user-auth](/dokku/development/plugin-triggers/#user-auth) plugin trigger to handle command authorization.
+
+## Adding deploy users
+
+You can add your public key to the dokku user's `~/dokku/.ssh/authorized_keys` file with the following command:
+
+```shell
+# from your local machine
+# replace dokku.me with your domain name or the host's IP
+# replace root with your server's root user
+# USER is the username you use to refer to this particular key
+cat ~/.ssh/id_rsa.pub | ssh root@dokku.me "sudo sshcommand acl-add dokku USER"
+```
+
+At it's base, the `sshcommand` *must* be run under a user with sudo access, as it sets keys for the dokku user.
+
+For instance, if you stored your public key at `~/.ssh/id_rsa.pub-open` and are deploying to EC2 where the default root-enabled user is `ubuntu`, you can run the following command to add your key under the `superuser` username:
+
+```
+cat ~/.ssh/id_rsa.pub-open | ssh ubuntu@dokku.me "sudo sshcommand acl-add dokku superuser"
+```
+
+If you are using the vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to dokku (it will use your host username as the `USER`):
+
+```
+cat ~/.ssh/id_rsa.pub | make vagrant-acl-add
+```
+
+## Scoping commands to specific users
+
+See the [user auth plugin trigger documentation](/dokku/development/plugin-triggers/#user-auth).

docs/template.html

@@ -117,6 +117,7 @@
             <a href="/dokku/remote-commands/" class="list-group-item">Remote Commands</a>
             <a href="/dokku/deployment/one-off-processes/" class="list-group-item">One Off Processes/Cron</a>
             <a href="/dokku/process-management/" class="list-group-item">Scaling Apps</a>
+            <a href="/dokku/deployment/user-management/" class="list-group-item">User Management</a>
             <a href="/dokku/checks-examples/" class="list-group-item">Zero Downtime Deploy Checks</a>
 
             <a href="#" class="list-group-item disabled">Configuration</a>