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, although limited instructions are also provided for Windows and Linux
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 (using the developer install procedure), 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; 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 Vagrant installed. Refer to the installation document for instructions.
OPTIONALLY install the latest stable release of VirtualBox. Installing VirtualBox will allow you to develop locally on your own machine, making your effort significantly reduced for things like Puppet development. 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.
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 (or their equivalents in your environment):
```
 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 from within your terminal window (you don't need to be root to run this command). You'll see something like this:

$ nepho
Updating cloudlet registry from: http://cloudlets.github.io/registry.yaml
Run nepho --help for a list of commands

You can run nepho --help for additional information about sub-commands and options.

Optional: Enable Command Completion

Users of Bash may take advantage of automatic command completion in Nepho. To do so, add the following line to your .bashrc:

[[ $(which nepho_completer) ]] && source nepho_completer

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. (Optional) 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.

The Cloudlet registry is updated automatically on a periodic basis, but to ensure it is up to date you can 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
```
Choose a blueprint. Each cloudlet contains one or more blueprints that are specific to machine configurations and infrastructure providers. Because you will be launching a local virtual machine via Vagrant, you will need to use a Vagrant-specific blueprint.

To view the list of available blueprints, run the following command:
```
 $ nepho blueprint list 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 the vagrant-single-host blueprint, 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.

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 -s
 [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 (i.e. us-east-1)>
 $ 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
```
The auto-updating display tracks the progress of your virtual machine deployment in Amazon EC2. When it is complete, nepho will show any outputs returned by Amazon CloudFormation. You can also use the CloudFormation console to view additional information.
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.

Installing additional cloudlets

The example cloudlet provides only minimal functionality; other cloudlets will automate the process of deploying applications or application platforms onto virtual machines.

Browse the available cloudlets. Nepho has the ability to download published cloudlets from the Internet, and provides search functionality.

To search for a cloudlet, use the following command:

 $ nepho cloudlet search example

The output will look something like this:

 $ nepho cloudlet search example
 Searching for 'example':
 --------------------------------------------------------------------------------
 Name:         nepho-example
 Version:      1.0.0
 Author:       Harvard University Information Technology
 License:      MIT
 Summary:      An example cloudlet that demonstrates key concepts.

You can also search without a search string, and all available cloudlets will be displayed:

 $ nepho cloudlet search
 Listing all cloudlets:
 --------------------------------------------------------------------------------
 <output snipped>

Install additional cloudlets as desired. Once you find the cloudlet you want, nepho can download and install it for you.

To install a cloudlet, run the following command:
```
 $ nepho cloudlet install <cloudlet name>
```

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly