split server.md into separate files and add Docker instructions

README.md

@@ -2,6 +2,8 @@
 
 This is the official documentation for [Anvil Connect](https://github.com/anvilresearch/connect) and related projects.
 
+## [Getting started](getting-started.md)
+
 ## Support
 
 ### Chat with us

clients.md

@@ -96,6 +96,76 @@ content-type: application/json
 
 ### REST API
 
+### Registration permissions
+
+Anvil Connect can be configured for three types of client registration: `dynamic`, `token`, or `scoped`, each being more restrictive than the previous option. The default `client_registration` type is `scoped`. Trusted clients require additional scope to register. This can be configured with the `trusted_registration_scope` setting, which defaults to `realm`.
+
+#### Dynamic Client Registration
+
+With `client_registration` set to `dynamic`, any party can register a client with the authorization server. Optionally, a bearer token may be provided in the authorization header per RFC6750. If a valid access token is presented with a registration request, the client will be associated with the user represented by that token.
+
+```json
+{
+  // ...
+  "client_registration": "dynamic",
+  // ...
+}
+```
+
+The following table indicates expected responses to *Dynamic Client Registration* requests.
+
+| trusted | w/token | w/scope | response  |
+|:-------:|:-------:|:-------:|----------:|
+|         |         |         | 201       |
+| x       |         |         | 403       |
+|         | x       |         | 201       |
+| x       | x       |         | 403       |
+| x       | x       | x       | 201       |
+|         | x       | x       | 201       |
+
+
+#### Token-restricted Registration
+
+Client registration can be restricted so that a valid user access token is required by setting `client_registration` to `token`. In this case, any request without a token will fail. As with *Dynamic Client Registration*, in order to register a trusted client, the access token must have sufficient scope.
+
+```json
+{
+  // ...
+  "client_registration": "token",
+  // ...
+}
+```
+
+| trusted | w/token | w/scope | response  |
+|:-------:|:-------:|:-------:|----------:|
+|         |         |         | 403       |
+| x       |         |         | 403       |
+|         | x       |         | 201       |
+| x       | x       |         | 403       |
+| x       | x       | x       | 201       |
+|         | x       | x       | 201       |
+
+#### Scoped Registration
+
+Third party registration can be restricted altogether with the `scoped` `client_registration` setting. In this case, all registration requires a prescribed `registration_scope`.
+
+```json
+{
+  // ...
+  "client_registration": "scoped",
+  // ...
+}
+```
+
+| trusted | w/token | w/scope | response  |
+|:-------:|:-------:|:-------:|----------:|
+|         |         |         | 403       |
+| x       |         |         | 403       |
+|         | x       |         | 403       |
+| x       | x       |         | 403       |
+| x       | x       | x       | 201       |
+|         | x       | x       | 201       |
+
 ## Client Properties
 
 #### redirect_uris

getting-started.md

@@ -0,0 +1,250 @@
+## Getting Started
+
+### Requirements
+
+Anvil Connect works with the latest versions of [Node.js][nodejs] (0.12.x) or
+[io.js][iojs] (3.x.x) and [Redis][redis] (3.0.x) and is tested on
+[Debian][debian], [Ubuntu][ubuntu], [Alpine][alpine] Linux distributions, and
+Mac OS X.
+
+The server and its dependencies can optionally run inside [Docker][docker]
+containers. We recommend using Docker Compose, although it is not required.
+[Installation instructions][docker-install] for Docker and related tools are
+available on the Docker website. On Mac and Windows you can easily set up a
+Docker environment using the [Docker Toolbox][docker-toolbox].
+
+[nodejs]: https://nodejs.org
+[iojs]: https://iojs.org
+[redis]: http://redis.io
+[debian]: https://www.debian.org
+[ubuntu]: http://www.ubuntu.com
+[alpine]: https://www.alpinelinux.org
+[docker]: https://www.docker.com
+[docker-install]: https://docs.docker.com/installation
+[docker-toolbox]: https://www.docker.com/toolbox
+
+
+### Initializing your project
+
+To get started with Anvil Connect, install the `anvil-connect-cli` package
+globally using npm.
+
+```bash
+$ npm install -g anvil-connect-cli
+```
+
+After this has completed successfully, you can generate all the files you'll
+need to run your own custom auth server.
+
+First, make a new directory and `cd` into it. Then, run `nvl init`.
+
+```
+$ mkdir myauthserver
+$ cd myauthserver
+$ nvl init
+```
+
+This command will prompt you for some essential information and choices about
+your deployment.
+
+With default options, `nv init` will generate all the files you
+need to customize and run Anvil Connect, with or without Docker, Redis and
+nginx, depending on your prompt selections.
+
+If you choose to use nginx, you'll also be prompted to create a new self-signed
+SSL certificate. You can opt out of any of the components other than Anvil
+Connect.
+
+```bash
+# defaults to the name of the current directory
+? What would you like to name your Connect instance?
+
+# FQDN of the auth server
+# This can be localhost, an IP address, or a (sub)domain
+? What (sub)domain will you use? connect.example.io
+
+# We recommend our default Docker setup, including
+# support for running Anvil Connect, Redis, and nginx
+# with Docker Compose. You can opt out of any or all
+# of this if Docker isn't your cup of tea.
+? Would you like to use Docker? Yes
+
+# We can generate a Redis configuration and optional
+# Dockerfile. You can also configure Anvil Connect to
+# run against any Redis instance available over the
+# network.
+? Would you like to run Redis? Yes
+
+# We recommend using nginx for SSL termination, load balancing,
+# and caching of static assets. If you wish to employ other means
+# answer "no".
+? Would you like to run nginx? Yes
+
+# With nginx or without it, be sure to use SSL in production
+? Would you like to create a self-signed SSL cert? Yes
+
+# If you opt "yes" to generating an SSL cert, you'll be
+# prompted for the certificate subject information.
+? Country Name (2 letter code) US
+? State or Province Name (full name) South Dakota
+? Locality Name (eg, city) Rapid City
+? Organization Name (eg, company) Anvil Research, Inc
+```
+
+Once finished, you'll have a directory containing all the files needed to run
+your auth server.
+
+We've structured the package so that you can customize your server without
+having to maintain a fork. You can add your own static assets, customize views
+(HTML templates), integrate custom auth protocols, manage project-specific
+dependencies, and keep all this, along with your configuration files, under
+version control using git. This setup makes upgrading Anvil Connect as simple
+as changing the version number in `connect/package.json` in most cases.
+
+
+## Run
+
+### Running locally
+
+A Redis instance needs to running locally or accessible over the network. Before you
+can run Anvil Connect, you'll also need to install npm and bower dependencies.
+
+```bash
+$ cd connect
+$ npm install
+$ bower install
+```
+
+You can run the server in `development` mode with:
+
+```bash
+$ node server.js
+```
+
+This will use the `config/development.json` settings. To run in production mode, set
+the `NODE_ENV` environment variable to `production`.
+
+```bash
+$ NODE_ENV=production node server.js
+```
+
+When Anvil Connect starts for the first time, it will check to see whether or
+not the Redis server at the configured hostname and port has any data inside and
+whether or not it contains data from a valid Anvil Connect instance.
+
+If Anvil Connect detects any existing data in the database, and it is not from
+an Anvil Connect instance, it will halt with the following error:
+
+```
+Redis already contains data, but it doesn't seem to be an Anvil Connect database.
+If you are SURE it is, start the server with --no-db-check to skip this check.
+```
+
+If you are sure that there is no conflicting data in Redis, for example,
+in the event that you may have edited Redis's data manually, start Anvil Connect
+with the `--no-db-check` flag.
+
+```bash
+$ node server.js --no-db-check
+```
+
+
+
+### Running in Docker Containers
+
+If you've opted to use Docker, Redis, and nginx, you should be ready to roll.
+You can use Docker Compose to run a complete, production-ready set of
+containers.
+
+First, you'll want to ensure a few things are in order.
+
+#### IP Address
+
+If you're running on Linux, Anvil Connect will be bound to localhost and/or the
+IP of your computer/server. Once the containers are running, you should be able
+to reach the service at `https://0.0.0.0`, `https://127.0.0.1`, or 
+`https://localhost`.
+
+
+On Mac once you've installed the [Docker Toolbox][docker-toolbox] you can get
+the IP address with the following command.
+
+```bash
+$ docker-machine ip default
+```
+
+#### /etc/hosts
+
+To work with your Anvil Connect instance locally, it's a good idea to make an
+entry in your `/etc/hosts` file. For example, on a Mac, you'll want to
+associate the (sub)domain you provided the generator with the IP address of 
+your Docker host.
+
+```bash
+192.168.99.100 connect.example.io
+```
+
+#### SSL Certificate
+
+When you ran `nv init`, you may have opted to generate a self-signed SSL
+certificate. The files were created in the `nginx/certs` directory of this
+project. If you did not opt to generate these files, you'll need to provide
+your own `nginx.key` and `nginx.crt` files in the `nginx/certs` directory.
+
+
+#### Start Anvil Connect with Docker Compose
+
+You can run these commands in the directory where you ran `nvl init`.
+
+```bash
+$ docker-compose up -d
+```
+
+#### Stop
+
+```
+$ docker-compose stop [connect|nginx|redis]
+```
+
+#### Restart
+
+```
+$ docker-compose restart
+```
+
+#### View Logs
+
+If you're having trouble reaching the running Anvil Connect instance, you can
+view the logs for each type of container with the following command.
+
+```
+$ docker-compose logs <connect|nginx|redis>
+```
+
+
+### Building Custom Containers
+
+By default, Docker Compose is configured to use images provided by Anvil
+Research on Docker Hub. You can build images yourself by commenting out the
+`image` property of a service in `docker-compose.yml` and uncommenting the
+`build` property like so:
+
+```yaml
+connect:
+  build: connect
+  #image: anvilresearch/connect
+  ...
+```
+
+While we highly recommend using the official images or provided Dockerfiles,
+if necessary you can modify them to suit your requirements. You can also push
+your own custom images to Docker Hub and use them to run Connect by referencing
+them in the `image` property in `docker-compose.yml`.
+
+```yaml
+connect:
+  #build: connect
+  image: <dockerhubusername>/connect
+```
+
+### [Configuring the server](server/configuration.md)