[PATCH docs] BZ 645124: Add end-to-end initial usage documentation - deltacloud-devel - Fedora mailing-lists

4 Nov 2010

---
 deltacloud.org/content/use.haml     |    8 +++
 deltacloud.org/lib/documentation.rb |    1 +
 docs/use.mdown                      |   87 +++++++++++++++++++++++++++++++++++
 3 files changed, 96 insertions(+), 0 deletions(-)
 create mode 100644 deltacloud.org/content/use.haml
 create mode 100644 docs/use.mdown

diff --git a/deltacloud.org/content/use.haml b/deltacloud.org/content/use.haml
new file mode 100644
index 0000000..8abaab7
--- /dev/null
+++ b/deltacloud.org/content/use.haml
@@ -0,0 +1,8 @@
+---
+title: Deltacloud - Documentation
+area: documentation
+extension: html
+filter:
+  - haml
+---
+= render(:partial => "external", :locals => { :path => '../docs/use.mdown' })
diff --git a/deltacloud.org/lib/documentation.rb b/deltacloud.org/lib/documentation.rb
index 4863732..676a7de 100644
--- a/deltacloud.org/lib/documentation.rb
+++ b/deltacloud.org/lib/documentation.rb
@@ -2,6 +2,7 @@ module DocumentationHelper
   def documentation_pages
     [
       { :href => 'documentation.html', :menu => 'Overview' },
+      { :href => 'use.html', :menu => 'Post-Install', :description => 'Post-installation End-to-End Usage Documentation' },
       { :href => "api.html" , :menu => 'REST API', :description => 'REST API definition' },
       { :href => "drivers.html" , :menu => 'Drivers', :description => 'Currently-supported drivers' },
       { :href => "framework.html" , :menu => 'Framework', :description => 'Framework for writing additional drivers' },
diff --git a/docs/use.mdown b/docs/use.mdown
new file mode 100644
index 0000000..e3b8f9c
--- /dev/null
+++ b/docs/use.mdown
@@ -0,0 +1,87 @@
+Now that you have successfully installed the set of deltacloud packages and run deltacloud-configure, you can use the web interface to start and manage instances. We'll be using EC2 as the 'back end' cloud provider for these instructions, although this is only one of many cloud services providers you can manage with deltacloud.
+
+#### Change Default Administrator Password ####
+
+The post-install default username/password combination is admin/password. We strongly recommend changing the default password as a basic protection against unauthorized use of your cloud resources.
+
+1. First browse to http://localhost/deltacloud/login
+
+1. In the Administer section, click 'System Settings', then Manage Users.
+
+1. Select the 'admin' user's radio button, and click 'edit' lefthand column, or just click the admin username link. Enter and confirm a new password and click 'save'.
+
+#### Add a Provider ####
+
+The next step is to add a cloud services Provider whose resources will be added to your Pool.
+
+1. In the Administer section, click 'System Settings', and then 'Manage Providers' in the resulting screen.
+
+1. On the 'Manage Providers' page, in the left hand-navigation column under 'Providers', click 'Add'.
+
+1. Enter a name for the provider (e.g. 'ec2') and for Provider URL, use 'http://localhost:3002/api'. You can test the provider URL by clicking 'Test Connection' and then add the provider if the connection test succeeds.
+
+You should now see your new provider listed on the left column labeled 'Providers,' and you should be at the Provider Summary for the new Provider.
+
+#### Add a Provider Account ####
+
+The Provider Account you add in this step will allow Deltacloud to access your Provider's resources using the account credentials.
+
+1. Click 'Provider Accounts' above the summary information area. Since you haven't previously added any accounts, you'll start at the NEW ACCOUNT form.
+
+1. Since we're using EC2, you will need five pieces of security credentials from EC2:
+    * Access Key ID
+    * Secret Access Key
+    * AWS Account ID
+    * EC2 x509 private key
+    * EC2 x509 public key
+
+
+    These can all be obtained via the [EC2 management console](https://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=acc...)
+
+    If you haven't already done so, you'll need to create a public/private X.509 pair and save them in your filesystem. EC2 naming convention for the private key is 'pk-ABCDEFG.pem', and for the public key, 'cert-HIJKLMN.pem'
+
+1. Enter these 5 credentials and give your Provider Account a name of your choosing (e.g. 'myEC2'). For now, leave the 'Quota Instance' field set to the default value of 'unlimited'.
+
+    (Note that if you test the account settings before clicking 'Add' you'll need to re-select your x.509 cert files.)
+
+#### Create a Template ####
+
+Now that your pool contains a cloud provider, you need to create an image to run an instance in your cloud. Please note that image building is currently supported only on 64-bit versions of Fedora 13, the platform we use for development and testing.
+
+1. In the 'Define' section, click 'Deployables'. Then in the left hand navigation bar, under CREATE NEW, click 'Template'.
+
+1. Give your template a name, and select 'Fedora 13 (64-bit)' for Platform Choice. Support for building RHEL images is forthcoming but not yet available.
+
+1. You'll see that you have the option to 'Add Software' packages from available repos, but refrain from adding any for your first image build. The default image for development contains a base set of packages that will allow you to do basic things like ssh in to your instance, etc. Once you're sure that your end-to-end setup is functional, you can experiment with adding packages to image builds.
+
+    Please also note the caveat that when using EC2 there is a 9.9GB image size limit, and exceeding it may lead to failed builds or instance starts. Aggregator does not precalculate image sizes.
+
+1. After saving your template, you should see it listed in all three sections of the Deployables screen: Templates, Assemblies and Deployables. For the moment, only Templates are functional. Select your new Template's radio button and click 'Build.'
+
+#### Build an Image ####
+
+1. On the following Build Request screen, be sure 'Amazon EC2' is checked as the Provider Format, and click 'Submit to Build'. You should now see the Builds screen with your new template in the 'RUNNING' table with 'queued' or 'building' status. Refresh this page periodically to check the progress of your build request.
+
+    If your build fails, you will see a new table listing failed builds. If the build succeeds, you will see it in a Completed table, with status of 'OK'.
+
+    Once your build has completed, you can use it to start an image. In the 'RUN' section, click 'Instance Management' and then the 'Launch Instance' button. Click the 'Launch' button under your new template's description.
+
+This brings you to the Launch Instance screen, where you should give your instance an identifying Name, select a hardware profile from the Hardware Profile dropdown, optionally choose a desired Realm, and then click 'Launch'. Typical instance start times are under five minutes, but your mileage may vary.
+
+Waiting for your new instance to start is an excellent time to confirm that your default security groups setting on EC2 allows connections via SSH on port 22. Consult EC2 documentation if you haven't already configured your default security group settings. This can be configured before, during, or after your instance's start up and takes effect immediately.
+
+#### Connect to Your New Instance ####
+
+Once you can see that your instance is in state 'running', you should download its ssh private key and try connecting to it.
+
+1. In the 'RUN' section, click 'Instance Management', select the radio button of your running instance, and click 'Instance Details'.
+
+1. Click the link to download your instance's ssh key and save it to your filesystem.
+
+1. 'chmod 600' the file you downloaded
+
+1. Now you should be able to connect with:
+
+       $ ssh -i the-key-you-downloaded.pem root@ec2-xxx-xxx-xxx-xxx.compute-1.amazonaws.com
+
+    (substituting your actual key filename and FQHN)
-- 
1.7.2.3


    