Tutorial added

couchbaselabs · Jul 19, 2011 · 0863808 · 0863808
1 parent 4d806f9
commit 0863808
Show file tree

Hide file tree

Showing 13 changed files with 153 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -70,6 +70,158 @@ If you specify an ExistingClusterHostPort, then newly launched
 nodes will inherit the configuration of the existing cluster,
 and the RAM quota input parameters will be ignored.
 
+# Tutorial - Your First Membase Cluster
+
+The following is a step-by-step tutorial of launching your first
+Membase cluster on EC2 using these CloudFormation templates.
+
+## Step 1
+
+First, get the templates...
+
+    git clone git://github.com/couchbaselabs/cloud-formation.git
+
+## Specifying A New Stack
+
+Point your web browser to the AWS Management Console, click on the
+'AWS CloudFormation' tab, and click 'Create New Stack'...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_create-new-stack.png"/>
+</div>
+
+Fill in a Stack Name (for example: 'my-membase').
+
+Then, choose to Upload a Template File.
+
+Then, specify an N-pack template file from the cloud-formation/packs
+subdirectory tree.
+
+Here, I've chosen a 3-pack of 32-bit Membase 1.7.0.  That means this
+template will launch 3 EC2 nodes and auto-join them into a 3-node
+cluster...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_upload-pack.png"/>
+</div>
+
+Click Continue, and next specify input parameters...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_specify-parameters.png"/>
+</div>
+
+At this point, just provide a RESTPassword and a KeyName.
+
+You can leave the InstanceType as 'm1.small' and other parameters also
+as their default values in this example.
+
+The KeyName is the name of an SSH Key Pair.
+
+If you don't have a SSH Key Pair registered in AWS yet, please see...
+
+    http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?generating-a-keypair.html
+
+Next, continuing the tutorial, click Continue and then 'Create
+Stack'...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_confirm-stack.png"/>
+</div>
+
+## Stack Creation Progress
+
+While your 3-pack of Membase is launching, you can enjoy a 6-pack of
+beer.  You can also track the launching of your Membase nodes in the
+Events tab for your 'my-membase' stack...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_create-in-progress.png"/>
+</div>
+
+## Membase Is Ready
+
+Once it's done, the Outputs tab for 'my-membase' will have the
+URL for the Membase management REST/web console UI...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_stack-output.png"/>
+</div>
+
+Clicking on that RESTWebConsoleURL will take you to the Membase
+login page.
+
+Use the Username of 'Administrator' and a Password of the RESTPassword
+that you specified earlier...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_membase-login.png"/>
+</div>
+
+Logging in will take you to Membase's Cluster Overview page...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_membase-overview.png"/>
+</div>
+
+You can see that 1 server is active and that 2 servers are Pending
+Rebalance, which means the shards have not yet been rebalanced across
+all 3 nodes in the cluster.
+
+If you don't see 3 servers yet, the other 2 are still launching and
+auto-joining, and please just wait a little bit.
+
+To rebalance your cluster, click on MANAGE -> Server Nodes.
+
+Then click on the Rebalance button...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_rebalance-needed.png"/>
+</div>
+
+While your cluster is rebalancing, you'll see live rebalance status...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws_rebalance-progress.png"/>
+</div>
+
+## Make The Graphs Dance
+
+You can also ssh onto one of those nodes...
+
+    $ ssh -i ~/.ssh/aws.pem ec2-user@50.16.69.108
+    Last login: Tue Jul 19 19:56:29 2011 from 208.185.212.98
+
+       __|  __|_  )  Amazon Linux AMI
+       _|  (     /     Beta
+      ___|\___|___|
+
+    See /usr/share/doc/system-release-2011.02 for latest release notes. :-)
+    [ec2-user@domU-12-31-39-02-D9-78 ~]$
+
+And then you can use memcachetest to drive some basic, synthetic test
+load onto your Membase cluster, on the default bucket...
+
+    [ec2-user@domU-12-31-39-02-D9-78 ~]$ /opt/membase/bin/memcachetest -l
+
+In your web browser, navigate to MONITOR -> Data Buckets -> default to
+see live, charted statistics.
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws-monitor.png"/>
+</div>
+
+Be sure to drill around -- the graphs can be very helpful to diagnose
+issues.
+
+Finally, in your EC2 tab in the AWS Management Console, your new EC2
+instances will be named with the prefix of 'my-membase' (the name of
+your stack), for easy tracking...
+
+<div>
+    <img src="https://github.com/couchbaselabs/cloud-formation/raw/master/docs/aws-instances.png"/>
+</div>
+
 # More info
 
 * http://couchbase.com
@@ -83,5 +235,6 @@ MIT - these templates were made for you.
 # TODO
 
 * EBS configuration
+* Publish the templates on S3 somewhere
 * Alerts configuration - nice to have
 * Elastic Load Balancer - nice to have
diff --git a/docs/aws-instances.png b/docs/aws-instances.png
diff --git a/docs/aws-monitor.png b/docs/aws-monitor.png
diff --git a/docs/aws_confirm-stack.png b/docs/aws_confirm-stack.png
diff --git a/docs/aws_create-in-progress.png b/docs/aws_create-in-progress.png
diff --git a/docs/aws_create-new-stack.png b/docs/aws_create-new-stack.png
diff --git a/docs/aws_membase-login.png b/docs/aws_membase-login.png
diff --git a/docs/aws_membase-overview.png b/docs/aws_membase-overview.png
diff --git a/docs/aws_rebalance-needed.png b/docs/aws_rebalance-needed.png
diff --git a/docs/aws_rebalance-progress.png b/docs/aws_rebalance-progress.png
diff --git a/docs/aws_specify-parameters.png b/docs/aws_specify-parameters.png
diff --git a/docs/aws_stack-output.png b/docs/aws_stack-output.png
diff --git a/docs/aws_upload-pack.png b/docs/aws_upload-pack.png