diff --git a/docs/en-US/API_Developers_Guide.ent b/docs/en-US/Developers_Guide.ent similarity index 100% rename from docs/en-US/API_Developers_Guide.ent rename to docs/en-US/Developers_Guide.ent diff --git a/docs/en-US/API_Developers_Guide.xml b/docs/en-US/Developers_Guide.xml similarity index 85% rename from docs/en-US/API_Developers_Guide.xml rename to docs/en-US/Developers_Guide.xml index c691ad02cf6..6c09354f6a8 100644 --- a/docs/en-US/API_Developers_Guide.xml +++ b/docs/en-US/Developers_Guide.xml @@ -24,14 +24,14 @@ - &PRODUCT; API Developer's Guide + &PRODUCT; Developer's Guide Apache CloudStack 4.0.0-incubating - How to integrate with &PRODUCT; using the &PRODUCT; API. + This guide shows how to develop &PRODUCT;, use the API for operation and integration, access the usage data and use &PRODUCT; specific tools to ease development, testing and integration. @@ -45,10 +45,12 @@ + + diff --git a/docs/en-US/building-devcloud.xml b/docs/en-US/building-devcloud.xml new file mode 100644 index 00000000000..5f792c375a2 --- /dev/null +++ b/docs/en-US/building-devcloud.xml @@ -0,0 +1,32 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Building DevCloud + The DevCloud appliance can be downloaded from the wiki at . It can also be built from scratch. Code is being developed to provide this alternative build. It is based on veewee, Vagrant and Puppet. + The goal is to automate the DevCloud build and make this automation capability available to all within the source release of &PRODUCT; + This is under heavy development. The code is located in the source tree under tools/devcloud + A preliminary wiki page describes the build at https://cwiki.pache.org/CLOUDSTACK/building-devcloud.html + +
diff --git a/docs/en-US/building-prerequisites.xml b/docs/en-US/building-prerequisites.xml new file mode 100644 index 00000000000..d97ca40f2a3 --- /dev/null +++ b/docs/en-US/building-prerequisites.xml @@ -0,0 +1,66 @@ + + +%BOOK_ENTITIES; +]> + + + + +
+ Build Procedure Prerequisites + In this section we will assume that you are using the Ubuntu Linux distribution with the Advanced Packaging Tool (APT). If you are using a different distribution or OS and a different packaging tool, adapt the following instructions to your environment. To build &PRODUCT; you will need: + + + git, http://git-scm.com + sudo apt-get install git-core + + + maven, http://maven.apache.org + sudo apt-get install maven + Make sure that you installed maven 3 + $ mvn --version +Apache Maven 3.0.4 +Maven home: /usr/share/maven +Java version: 1.6.0_24, vendor: Sun Microsystems Inc. +Java home: /usr/lib/jvm/java-6-openjdk-amd64/jre +Default locale: en_US, platform encoding: UTF-8 +OS name: "linux", version: "3.2.0-33-generic", arch: "amd64", family: "unix" + + + java + set the JAVA_HOME environment variable + $ export JAVA_HOME=/usr/lib/jvm/java-6-openjdk + + + + In addition, to deploy and run &PRODUCT; in a development environment you will need: + + + Mysql + sudo apt-get install mysql-server-5.5 + Start the mysqld service and create a cloud user with cloud as a password + + + Tomcat 6 + sudo apt-get install tomcat6 + + + +
diff --git a/docs/en-US/building-with-maven-deploy.xml b/docs/en-US/building-with-maven-deploy.xml new file mode 100644 index 00000000000..e4b9801aa30 --- /dev/null +++ b/docs/en-US/building-with-maven-deploy.xml @@ -0,0 +1,39 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Deployment and Testing Steps + Deploying the &PRODUCT; code that you compiled is a two step process: + + If you have not configured the database or modified its properties do: + mvn -P developer -pl developer -Ddeploydb + + Then you need to run the &PRODUCT; management server. To attach a debugger to it, do: + export MAVEN_OPTS="-Xmx1024 -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n" + mvn -pl :cloud-client-ui jetty:run + + + When dealing with the database, remember that you may wipe it entirely and lose any data center configuration that you may have set previously. +
+ diff --git a/docs/en-US/building-with-maven-steps.xml b/docs/en-US/building-with-maven-steps.xml new file mode 100644 index 00000000000..319654fb290 --- /dev/null +++ b/docs/en-US/building-with-maven-steps.xml @@ -0,0 +1,33 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Building Steps + &PRODUCT; uses git for source version control, first make sure you have the source code by pulling it: + git clone https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git + Several Project Object Models (POM) are defined to deal with the various build targets of &PRODUCT;. Certain features require some packages that are not compatible with the Apache license and therefore need to be downloaded on your own. Check the wiki for additional information https://cwiki.apache.org/CLOUDSTACK/building-with-maven.html. In order to build all the open source targets of &PRODUCT; do: + mvn clean install + The resulting jar files will be in the target directory of the subdirectory of the compiled module. +
+ diff --git a/docs/en-US/building-with-maven.xml b/docs/en-US/building-with-maven.xml new file mode 100644 index 00000000000..5363b1d754a --- /dev/null +++ b/docs/en-US/building-with-maven.xml @@ -0,0 +1,32 @@ + + +%BOOK_ENTITIES; +]> + + + + + Using Maven to Build &PRODUCT; + + + + + + diff --git a/docs/en-US/devcloud-usage-mode.xml b/docs/en-US/devcloud-usage-mode.xml new file mode 100644 index 00000000000..bb65f904ccd --- /dev/null +++ b/docs/en-US/devcloud-usage-mode.xml @@ -0,0 +1,60 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ DevCloud Usage Mode + DevCloud can be used in several different ways: + + + Full sandbox. Where &PRODUCT; is run within the DevCloud instance started in Virtual Box. + In this mode, the &PRODUCT; management server runs within the instance and nested virtualization allows instantiation of tiny VMs within DevCloud itself. &PRODUCT; code modifications are done within DevCloud. + The following diagram shows the architecture of the SandBox mode. + + + + + + DevCloud.png: Schematic of the DevCloud SandBox architecture + + + + + A deployment environment. Where &PRODUCT; code is developed in the localhost of the developer and the resulting build is deployed within DevCloud + This mode was used in the testing procedure of &PRODUCT; 4.0.0 incubating release. See the following screencast to see how: http://vimeo.com/54621457 + + + A host-only mode. Where DevCloud is used only as a host. &PRODUCT; management server is run in the localhost of the developer + This mode makes use of a host-only interface defined in the Virtual Box preferences. Check the following screencast to see how: http://vimeo.com/54610161 + The following schematic shows the architecture of the Host-Only mode. + + + + + + DevCloud-hostonly.png: Schematic of the DevCloud host-only architecture + + + + +
diff --git a/docs/en-US/devcloud.xml b/docs/en-US/devcloud.xml new file mode 100644 index 00000000000..677818700ae --- /dev/null +++ b/docs/en-US/devcloud.xml @@ -0,0 +1,38 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ DevCloud + DevCloud is the &PRODUCT; sandbox. It is provided as a Virtual Box appliance. It is meant to be used as a development environment to easily test new &PRODUCT; development. It has also been used for training and &PRODUCT; demos since it provides a Cloud in a box. + + DevCloud is provided as a convenience by community members. It is not an official &PRODUCT; release artifact. + The &PRODUCT; source code however, contains tools to build your own DevCloud. + + + DevCloud is under development and should be considered a Work In Progress (WIP), the wiki is the most up to date documentation: + + + + +
diff --git a/docs/en-US/developer-introduction.xml b/docs/en-US/developer-introduction.xml index bb5251b4f26..9d54f31dae9 100644 --- a/docs/en-US/developer-introduction.xml +++ b/docs/en-US/developer-introduction.xml @@ -23,7 +23,7 @@ --> - Introduction for Developers + Introduction to the &PRODUCT; API diff --git a/docs/en-US/images/DevCloud-hostonly.png b/docs/en-US/images/DevCloud-hostonly.png new file mode 100644 index 00000000000..111f93ac700 Binary files /dev/null and b/docs/en-US/images/DevCloud-hostonly.png differ diff --git a/docs/en-US/images/DevCloud.png b/docs/en-US/images/DevCloud.png new file mode 100644 index 00000000000..5e83ca946c7 Binary files /dev/null and b/docs/en-US/images/DevCloud.png differ diff --git a/docs/en-US/marvin.xml b/docs/en-US/marvin.xml new file mode 100644 index 00000000000..062616ac888 --- /dev/null +++ b/docs/en-US/marvin.xml @@ -0,0 +1,32 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Marvin + Marvin is the &PRODUCT; automation framework. It originated as a tool for integration testing but is now also used to build DevCloud as well as to provide a Python &PRODUCT; API binding. + + Marvin's complete documenation is on the wiki at https://cwiki.apache.org/CLOUDSTACK/testing-with-python.html + The source code is located at tools/marvin + +
diff --git a/docs/en-US/source-build.xml b/docs/en-US/source-build.xml new file mode 100644 index 00000000000..33218962174 --- /dev/null +++ b/docs/en-US/source-build.xml @@ -0,0 +1,49 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Building &PRODUCT; from Source + + Prior to the 4.0.0 incubating release, Ant was used to build &PRODUCT;. Starting with 4.0.0 a migration to Maven is underway. + The website and the wiki contain up to date information on the build procedure at: + + https://cwiki.apache.org/CLOUDSTACK/building-with-maven.html + http://incubator.apache.org/cloudstack/develop/environment.html + + + The overarching steps to build &PRODUCT; are:. + + Install the prerequisites and setup your environment + Understand that various Maven profiles and build targets + Deploy and test your build + If needed, learn how to build binaries + + + + Learning Maven is outside the scope of this documentation. + Go to the Maven website at http://maven.apache.org/guides/getting-started/index.html + + +
+ diff --git a/docs/en-US/tools.xml b/docs/en-US/tools.xml new file mode 100644 index 00000000000..66fe894e171 --- /dev/null +++ b/docs/en-US/tools.xml @@ -0,0 +1,29 @@ + + +%BOOK_ENTITIES; +]> + + + + + Tools + + + diff --git a/docs/publican-devguide.cfg b/docs/publican-devguide.cfg index 006c0d16d00..a8e28aea37b 100644 --- a/docs/publican-devguide.cfg +++ b/docs/publican-devguide.cfg @@ -20,7 +20,7 @@ xml_lang: en-US type: Book -docname: API_Developers_Guide +docname: Developers_Guide brand: cloudstack chunk_first: 1 chunk_section_depth: 1