update APIRS documentation for cloud deployments (#1773)

docs/cluster.md

@@ -22,7 +22,6 @@ Management Commands:
 
 Commands:
   create      Set up a cluster in swarm mode
-  ls          List deployed amp clusters
   rm          Destroy an amp cluster
   status      Retrieve details about an amp cluster
 
@@ -43,7 +42,7 @@ This is the default mode.
 
 * To create a cluster locally:
 ```
-$ amp cluster create --local-fast
+$ amp cluster create --local-no-logs --local-no-metrics
 ...
 2017/08/04 01:17:59 ampctl (version: 0.14.0-dev, build: 08772ef3)
 ...
@@ -68,6 +67,6 @@ If the secret is already created, it will be used as is without any modification
 
 #### Creating a cluster on AWS
 
-To target AWS, you should use the --provider aws option.
+To target AWS, you should use the --provider aws option, refer to the help for details on aws options: `amp cluster create -h`.
 
-More details on the AWS creation on the [AMP wiki](https://github.com/appcelerator/amp/wiki/AMP-deployment-on-AWS)
+More details on the AWS creation on the [AMP wiki](https://github.com/appcelerator/amp/wiki/AMP-Clusters-deployment-on-AWS)

examples/stacks/apirs/README.md

@@ -36,12 +36,20 @@ Build the `kvcodec` tool in order to prepare your consul KV configuration and ru
 
     $ go build -o kvcodec .
 
+Make sure your amp CLI is at least version 0.17.0.
+
+If you plan to deploy on AWS, prepare your AWS credentials. The recommended way is to use the [~/.aws/credentials file](http://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html) but you can also pass the access key id and the secret access key as parameter to the CLI, as described in `amp cluster create -h`.
+
 ## Local Deployment
 
+For local deployments you won't have S3 buckets or NFS servers, unless you set it by your own means.
+
 ### Cluster creation & sign up
     amp cluster create
     amp -k user signup
 
+No need to verify the login, because it's a local deployment, you're logged in by default (relaxed security for dev environments).
+
 ### Configuration
 The `consul.json` file is configured for local deployments. You only need to generate your Consul KV configuration file using the following command:
 
@@ -66,19 +74,65 @@ Run in this directory:
 
 ## Cloud Deployment
 
+Full instructions on cluster deployment on AWS is available on the [amp wiki](https://github.com/appcelerator/amp/wiki/AMP-Clusters-deployment-on-AWS), the following section is a quick guide adapted to the APIRS use case.
+
 ### Cluster creation & sign up
 
     export STACK_NAME=amp-$USER
     export STACK_NAME=YOUR_KEYPAIR
 
-    amp cluster create --provider aws --aws-region us-west-2 --aws-stackname $STACK_NAME --aws-parameter KeyName=$KEYPAIR_NAME --aws-sync --aws-parameter NFSEndpoint=true
-    # the output will show the URL of the cluster. It should be used below for the REMOTE_SERVER variable.
+#### Create cluster
+
+    amp cluster create --provider aws --aws-region us-west-2 --aws-stackname $STACK_NAME --aws-parameter KeyName=$KEYPAIR_NAME --aws-parameter NFSEndpoint=true
+
+the output will show the URL of the cluster. We'll refer to is as $REMOTE_SERVER.
+it will also show the NFS endpoint. We'll refer to is as $NFS_ENDPOINT.
+
     export REMOTE_SERVER="URL of the cluster"
+    export NFS_ENDPOINT="URL of the NFS server"
 
+PS: if you don't want to store your credentials in the ~/.aws/ folder, you can alternatively use CLI arguments to pass the credentials:
+
+      --aws-access-key-id YOUR_ACCESS_KEY_ID --aws-secret-access-key YOUR_SECRET_ACCESS_KEY
+
+#### Enable user registration
+
+this is a cloud cluster creation, the user registration will go through email notifications and will require a user verification.
+to use this feature, the cluster requires a SendGrid key, without it the user registration will fail
+First, obtain a Sendgrid key. You can get a 30 days trial here: https://app.sendgrid.com/signup?id=71713987-9f01-4dea-b3d4-8d0bcd9d53ed
+
+ssh to a manager node
+update the amplifier configuration with the following lines:
+
+    cat > amplifier.yml << EOF
+    EmailKey: _SENDGRID_KEY_
+    SUPassword: _SUPER_USER_PASSWORD_
+    JWTSecretKey: _JWT_RANDOM_STRING_
+    EOF
+    cat amplifier.yml | docker secret create amplifier_yml_custom -
+    docker service update --secret-rm amplifier_yml --secret-add source=amplifier_yml_custom,target=/run/secrets/amplifier.yml amp_amplifier
+
+Register your user:
+
     amp -k -s $REMOTE_SERVER user signup
-    # followed by user verification and login
+    # followed by user verification and login (as detailed in the email notification)
+
+
+#### Adding object storage
+
+You can now add object storage for APIRS. In the following command we'll use BUCKET1 and BUCKET2, you should use your own unique names.
+
+Create the new buckets:
+
+    amp -k -s $REMOTE_SERVER object-store create BUCKET1
+    amp -k -s $REMOTE_SERVER object-store create BUCKET2
+
+List the existing buckets available in the cluster, make sure you see BUCKET1 and BUCKET2:
+
+    amp -k -s $REMOTE_SERVER object-store list
 
 ### Configuration
+
 The `consul.json` file is configured for local deployments. You need to replace the all the domain names occurrences 
 in `consul.json` from `apirs.local.appcelerator.io` to the domain you're going to use. For instance:
 
@@ -94,6 +148,7 @@ Then you need to create the following Docker `config`s:
     amp -k -s $REMOTE_SERVER config create consul_kv kv.json
 
 ### Deploying the stacks
+
     amp -k -s $REMOTE_SERVER config stack deploy -c apirs.stage1.yml
     # Check point: amp -k -s $REMOTE_SERVER service ps apirs_mongo-primary
 
@@ -105,6 +160,8 @@ Then you need to create the following Docker `config`s:
 
     curl -k -H Host:acs.apirs.local.appcelerator.io https://$REMOTE_SERVER/v1/admins/ping.json
 
+This last line simulates a DNS alias by using a HTTP header, but if you set a real DNS record as a CNAME resolving to $REMOTE_SERVER, it can be used directly in curl or a browser.
+
 ## Links
 
 * Mongo: https://mongo.apirs.local.appcelerator.io