Quick-Start-Guide.md

Quick-Start Guide

This guide covers:

1. Running SilverKing on AWS - try out SilverKing using our template AMI
2. Building Silverking on AWS - build SilverKing on your own instance(s) and try out SilverKing

Running Simple AWS-based Instances

Getting the launch host started

If you'd like to give SilverKing a try, you can be up and running in minutes using an AWS instance from our template:
 SilverKing AMI (ctrl+click to open in new tab)
 AMI-Name: SilverKing
 Platform: Amazon Linux
 Username: ec2-user
 Region: US West (Oregon)

1. In the AWS console, right click on the selected AMI -> "Launch"
2. Choose an Instance Type: choose atleast a t2.micro
3. Configure Instance:
   
   • Network: I'm just using my default vpc
     *Make sure whatever VPC you are using with your instance, dns resolution and hostnames are both set to 'yes':
     *You can view your VPC's here (ctrl+click to open in new tab)
   • Auto-assign Public IP: we want this enabled so that we can ssh into this instance from a shell, like putty
   • IAM role: we need to add a role so that we can programmatically call AWS api's, which is required to run our silverking cloud script
     *If you don't have an EC2 IAM role, you need to create one (ctrl+click to open in new tab):
     • Click "Create role"
     • AWS service->EC2, Click "Next: Permissions"
     • Search: "AmazonEC2FullAccess", Select Check Box for "AmazonEC2FullAccess" Policy, Click "Next: Review"
     • Role name: "EC2Admin"
     • Click "Create role" button
4. Add Storage: I'm just using the defaults
5. Add Tags: I skip this
6. Configure Security Group: I select my normal security group that I use for all my AWS usage
   *Make sure your security group contains an Inbound Rule for All Traffic with your security group ID as the Source:
   
7. Review Instance Launch: Click "Launch"

Starting SK/SKFS

Once you have an instance running, ssh into this instance (this is the master/launch host).
You can run SilverKing on just this instance or on many instances.

cd ~/SilverKing/bin/

We tell SKCloudAdmin how many number of AWS instances we want to run. If we pass in "-n 1", the script won't launch any more instances because we already have one, this instance, but if we pass in something like "-n 5", the script will launch 4 more instances for a total of 5.
Let's keep it relatively simple and use a total of 3 AWS instances, including this launch host, so "-n 3":

./SKCloudAdmin.sh -c LaunchInstances -n 3   # this fires up the instances, preps them i.e. wires up ssh'ing capability between instances, starts zookeeper, and does some SilverKing prep work

You should now see 2 additional instances running in your AWS console.
Once the script returns, it should inform us of what command we run to start the SilverKing cluster:

./SKAdmin.sh -G ~/SilverKing/bin/cloud_out -g GC_SK_cloud -c StartNodes,CreateSKFSns,CheckSKFS  # this starts sk and skfs

That's it! SilverKing is up and running. You can run 'ps uxww' to see both processes - sk and skfs.

You can now perform key-value operations using the skc tool (skc usage):

~/SilverKing/bin/skc -G ~/SilverKing/bin/cloud_out -g GC_SK_cloud    
skc> h;         # help menu
skc> cn testNs; # this creates a namespace
skc> p k1 v1;   # this puts a key: k1, with value: v1
skc> g k1 v1;   # gets the values for keys: k1 and v1
        k1 => v1
        v1 => <No such value>
skc> q;         # quit

You can also use the SKFS file system:

cd /var/tmp/silverking/skfs/skfs_mnt/skfs
echo World > Hello
cat Hello

To shut down the SilverKing cluster:

cd ~/SilverKing/bin

./SKAdmin.sh -G ~/SilverKing/bin/cloud_out -g GC_SK_cloud -c StopSKFS,StopNodes  # this stops sk and skfs

To terminate the AWS instances:

./SKCloudAdmin.sh -c TerminateInstances    # this terminates all the worker instances. this current master/launcher instance will still be running, and you can terminate it using the AWS console 

Building SilverKing on AWS

You may also build SilverKing on AWS using simplified build scripts for both Amazon Linux and Ubuntu.

Amazon Linux

sudo yum -y install git ksh
cd ~
git clone https://github.com/MorganStanley/SilverKing.git
~/SilverKing/build/aws/build_amazon_linux.sh

Ubuntu

sudo apt-get -y update 
sudo apt-get -y install git ksh    # 'apt-get update' first, or else you will get: "E: Unable to locate package ksh"
cd ~
git clone https://github.com/MorganStanley/SilverKing.git
~/SilverKing/build/aws/build_ubuntu.sh