Getting Started

So, you want to try out nepho? Great! This guide will step you through the process of installing a released version of nepho.

Goals

When you get to the end of this guide, you will be able to do the following:

Deploy a standalone virtual machine that runs on your local workstation
Deploy a standalone virtual machine that runs on Amazon EC2
Install additional "cloudlet" packages to extend nepho's functionality

Requirements

This guide assumes that the following conditions are met:

You're using a Mac, running OS X 10.7, 10.8, or 10.9
You have the ability to run commands with administrative (root) privileges
You have an Amazon Web Services account
Your computer has an Internet connection

If you can't meet all of these conditions, don't despair; you may not be able to access the full functionality of nepho, or you may have to do some extra work to complete the installation. However, we do our development on various versions of Mac OS X, so at present that's the platform that we support the best.

We have had reports of successful installation on Red Hat Enterprise Linux, and also on various versions of Windows.

Procedure

Installation

Please follow this procedure step by step. If you aren't able to complete a step, don't just continue on; later steps build upon prior steps. If you are unable to complete a step, please open an issue on our issue tracker.

Make sure you have a Python distribution installed, version 2.7 or newer. Mac OS X comes with Python pre-installed, as do many Linux distributions; Windows users will need to install Python themselves before proceeding. Linux users will need to make sure that the Python development package is installed as well as the runtime package. Note: we do not currently support Python 3.
Make sure you have Git installed. Mac OS X 10.8 and 10.9 users will need to install [Xcode]/(https://developer.apple.com/xcode/); Mac OS X 10.7 users will need to install a separate Git distribution as well. We recommend GitHub for Mac. Linux users should use their distribution's package management utilities to install Git; Windows users can try GitHub for Windows.
Make sure you have the latest stable release of VirtualBox installed. Refer to the installation document for instructions. Nepho does not require that the optional VirtualBox Extension Pack be installed, but it does no harm to install the Extension Pack.
Make sure you have the latest stable release of Vagrant installed. Refer to the installation document for instructions.
Open a terminal window. Mac OS X users should open Terminal.app, available by default in Applications/Utilities. Linux users can use xterm, GNOME Teminal, or Konsole; Windows users can use Cmd.exe.
Run the following commands:
```
 sudo easy_install pip
 sudo pip install setuptools-git
 sudo pip install nepho
```
If any of these commands generate error messages, you'll need to stop and troubleshoot the problem before proceeding, then try the command again. Once sudo pip install nepho completes, however, you will have installed nepho and all of its dependencies, and can proceed to the next section of this guide.

You'll know you've completed this section of the guide when you can run nepho --help from within your terminal window (you don't need to be root to run this command). You'll see something like this:

$ nepho --help
Updating cloudlet registry from: http://cloudlets.github.io/registry.yaml
usage: nepho <command> <action> [options]

Command line cross-cloud orchestration tool for constructing virtual datacenters.

commands:

  blueprint
    list and view individual cloudlet deployment blueprints

  cloudlet
    find, download, and manage cloudlets

  parameter
    list, view and modify parameter settings

  scope
    set a cloudlet (and optionally blueprint) scope for future commands

  stack
    create, manage, and destroy stacks built from blueprints

optional arguments:
  -h, --help  show this help message and exit
  --debug     toggle debug output
  --quiet     suppress all output

Local Virtual Machine Deployment

This section of the guide assumes that you have successfully completed every step in the previous section; if you haven't, you may want to go back and try again before continuing.

Open a terminal window. Mac OS X users should open Terminal.app, available by default in Applications/Utilities. Linux users can use xterm, GNOME Teminal, or Konsole; Windows users can use Cmd.exe.
Update the cloudlet registry. Cloudlets are packages of nepho code that serve as recipes to guide nepho's operations; for example, a cloudlet might provide instructions for deploying an application stack on a single host for development work, and also for deploying an application stack across multiple virtual instances.

To update the cloudlet registry, run the following command:
```
 $ nepho cloudlet update-registry
```
Install the example cloudlet. We've published an example cloudlet which provides recipes for a basic virtual machine, to be deployed either on the local workstation or on Amazon EC2.

To install the example cloudlet, run the following command:
```
 $ nepho cloudlet install nepho-example
```
Set your scope appropriately. Nepho commands take a number of options, and can get long and unwieldy. To streamline this process, we provide the option of setting a command "scope", which saves you from having to type the same commands over and over again.

To set your scope to use the nepho-example cloudlet and deploy a local virtual machine, run the following command:
```
 $ nepho scope set nepho-example vagrant-single-host
```

Deploy the virtual machine. Nepho groups cloud resources into "stacks"; in this example, the stack consists of only one virtual machine, but in other configurations could include virtual networks, load balancers, database resources etc.

To deploy the virtual machine, run the following command:

 $ nepho stack deploy

This step will take some time to complete; it'll take longer the first time because your workstation will need to download a virtual machine image from the Internet, then launch it, and then perform some post-launch configuration. A successful deployment looks like this:

 $ nepho stack deploy
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
  Using default command scope nepho-example vagrant-single-host
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 Nepho Elves are now building your Stack.... this may take a couple of minutes.
 <time passes>
 Vagrant Environment created! Access your stack with "nepho stack access <cloudlet> <blueprint>" or "vagrant ssh"

Connect to your newly deployed virtual machine. Once nepho tells you your stack is deployed, you can connect to it via SSH. You can easily escalate to administrative (root) privileges on your virtual machine, at which point you have full control over it; you can install software, test applications, and more.

To connect to your virtual machine, run the following command:

 $ nepho stack access

A successful connection to a locally running virtual machine looks like this:

 $ nepho stack access
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
  Using default command scope nepho-example vagrant-single-host
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 ---
 This system is for authorized users at Harvard University.
             Unauthorized Access is Prohibited.
 ---

 ******  Harvard University Information Technology  *******
 ********************* (617) 495-7777 *********************
 [vagrant@logus ~]$ sudo su -
 [root@logus ~]#

This transcript shows a nepho user connecting to a locally running virtual machine, and then becoming root.

Shut down your virtual machine when you've finished working with it. Running a virtual machine on your workstation consumes system resources; to free these up, shut down your virtual machine when you have no further need of it.

To shut down your virtual machine, run the following command:
```
 $ nepho stack destroy
```

Amazon EC2 Virtual Machine Deployment

This section of the guide assumes that you have successfully completed every step in the previous section; if you haven't, you may want to go back and try again before continuing.

If you haven't already, perform steps 1 through 3 from the previous section (Local Virtual Machine Deployment).
Set your scope appropriately.

To set your scope to use the nepho-example cloudlet and deploy a virtual machine on Amazon EC2, run the following command:
```
 $ nepho scope set nepho-example aws-single-host
```
Save your AWS credentials as nepho parameters. Nepho saves user-specific or cloudlet-specific information as "parameters"; since everyone's AWS credentials are different, you need to provide yours to nepho before it can deploy a virtual machine for you.

To configure the necessary parameters, run the following commands:
```
 $ nepho parameter set AWSAccessKeyID <your AWS public key>
 $ nepho parameter set AWSSecretAccessKey <your AWS private key>
 $ nepho parameter set AWSRegion <your AWS region>
 $ nepho parameter set KeyName <your desired EC2 key pair name>
```

Deploy the virtual machine.

To deploy the virtual machine, run the following command:

 $ nepho stack deploy

A successful deployment looks like this:

 $ nepho stack deploy
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
  Using default command scope nepho-example aws-single-host
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
  - Archiving payload for upload to S3
  - Creating S3 bucket for payload
  - Uploading payload archive to S3
 The Nepho elves are now building your stack. This may take a few minutes.
 Your stack ID is arn:aws:cloudformation:us-east-1:437323568624:stack/nepho-example-aws-single-host/7d278860-56e1-11e3-9eb3-50e2416294a8.
 You can monitor creation progress here: https://console.aws.amazon.com/cloudformation/home

As the output says, at this point your virtual machine is being deployed in Amazon EC2, but its deployment may not yet be complete. Use the Amazon CloudFormation console to monitor its progress.

Connect to your newly deployed virtual machine. Once you have confirmed via the Amazon CloudFormation console that your stack is deployed, you can connect to it via SSH. You can easily escalate to administrative (root) privileges on your virtual machine, at which point you have full control over it; you can install software, test applications, and more.

To connect to your virtual machine, run the following command:
```
 $ nepho stack access
```
Shut down your virtual machine when you've finished working with it. In order to avoid needless AWS usage charges, shut down your virtual machine when you have no further need for it.

To shut down your virtual machine, run the following command:
```
 $ nepho stack destroy
```
This will start the process of shutting down your virtual machine; you can monitor the shutdown via the Amazon CloudFormation console, but you don't need to do anything further to ensure your virtual machine shuts down.

Support

For further assistance, please contact the HUIT Cloud Engineering Team via our issue tracker. You can learn more about what we're doing at the HUIT Cloud Engineering blog, and you can learn more about Harvard's overall cloud strategy at the Harvard Cloud Services site.

HUIT Cloud Engineering Team
vim:ft=markdown

Provide feedback

Saved searches

Use saved searches to filter your results more quickly