diff --git a/INSTALL.md b/INSTALL.md index 54d02512ba2..61ebadfdc3d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,19 +1,16 @@ -This document describes how to set up and configure a single server CloudStack -development environment. If you aren't looking for a development environment, -the easiest way to deploy CloudStack is by using RPM or DEB packages from: +This document describes how to develop, build, package and install Apache CloudStack +(Incubating). For more information please refer to the project's website: - - http://cloudstack.org/download.html - - http://jenkins.cloudstack.org (CI/Build server) - - http://cloudstack.apt-get.eu (Debian repository) + http://incubator.apache.org/cloudstack -CloudStack developers use various platforms for development, this guide will -focus on CentOS and was tested against a CentOS 6.2 x86_64 setup. +Apache CloudStack developers use various platforms for development, this guide +was tested against a CentOS 6.2 x86_64 setup. Refer to the [wiki](http://cwiki.apache.org/confluence/display/CLOUDSTACK/Index) for the latest information, especially: - - [Setting up development environment](https://cwiki.apache.org/confluence/display/CLOUDSTACK/Setting+up+CloudStack+Development+Environment) for CloudStack. - - [Building](https://cwiki.apache.org/confluence/display/CLOUDSTACK/Building+with+Maven) CloudStack. + - [Setting up development environment](https://cwiki.apache.org/confluence/display/CLOUDSTACK/Setting+up+CloudStack+Development+Environment) for Apache CloudStack. + - [Building](https://cwiki.apache.org/confluence/display/CLOUDSTACK/Building) Apache CloudStack. ## Setting up Development Environment @@ -32,7 +29,7 @@ Set up Maven (3.0.4): $ echo export M2_HOME=/usr/local/apache-maven-3.0.4 >> ~/.bashrc # or .zshrc or .profile $ echo export PATH=${M2_HOME}/bin:${PATH} >> ~/.bashrc # or .zshrc or .profile -Note: Tomcat 6.0.35 has some known issue with CloudStack, please use Tomcat +Note: Tomcat 6.0.35 has some known issue with Apache CloudStack, please use Tomcat 6.0.33 from http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.33/bin ### Configure Environment @@ -50,22 +47,22 @@ Generate you ssh keys, useful for ssh-ing to your hosts and vm etc.: $ ssh-keygen -t rsa -q -CloudStack uses some ports, make sure at least those used by the management +Apache CloudStack uses some ports, make sure at least those used by the management server are available and not blocked by any local firewall. Following ports are -used by CloudStack and its entities: +used by Apache CloudStack and its entities: -8787: CloudStack (Tomcat) debug socket -9090, 8250: CloudStack Management Server, User/Client API -8096: User/Client to CloudStack Management Server (unauthenticated) -3306: MySQL Server -3922, 8250, 80/443, 111/2049, 53: Secondary Storage VM -3922, 8250, 53: Console Proxy VM -3922, 8250, 53: Virtual Router -22, 80, 443: XenServer, XAPI -22: KVM -443: vCenter -DNS: 53 -NFS: 111/2049 + 8787: Apache CloudStack (Tomcat) debug socket + 9090, 8250: Apache CloudStack Management Server, User/Client API + 8096: User/Client to CloudStack Management Server (unauthenticated) + 3306: MySQL Server + 3922, 8250, 80/443, 111/2049, 53: Secondary Storage VM + 3922, 8250, 53: Console Proxy VM + 3922, 8250, 53: Virtual Router + 22, 80, 443: XenServer, XAPI + 22: KVM + 443: vCenter + DNS: 53 + NFS: 111/2049 ### Configuring MySQL Server @@ -92,33 +89,45 @@ For example, for master: ## Building -Populate the dependencies using Maven: - $ mvn -P deps - -Clean previous build, if needed: +Clean and build: $ mvn clean - $ ant clean-all - $ ant clean-tomcat + $ mvn install -Build all sub-modules: +In case you want support for VMWare, SRX and other non-Apache (referred to as nonoss) +compliant libs, you may download the following jar artifacts from respective vendors: - $ ant build-all + deps/cloud-iControl.jar + deps/cloud-manageontap.jar + deps/cloud-netscaler-sdx.jar + deps/cloud-netscaler.jar + deps/vmware-apputils.jar + deps/vmware-vim.jar + deps/vmware-vim25.jar -Deploy the built project on tomcat: +Install them to ~/.m2 so maven can get them as dependencies: - $ ant deploy-server + $ cd deps + $ ./install-non-oss.sh + +And build them with the nonoss flag: + + $ mvn install -Dnonoss Clear old database (if any) and deploy the database schema: - $ ant deploydb + $ mvn -P developer -pl developer -Ddeploydb -Start the management server in debug mode: +Export the following variable if you need to run and debug the management server: - $ ant debug + $ export MAVEN_OPTS="-Xmx1024m -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n" -If this works, you've successfully setup a single server CloudStack installation. +Start the management server: + + $ mvn -pl :cloud-client-ui jetty:run + +If this works, you've successfully setup a single server Apache CloudStack installation. Open the following URL on your browser to access the Management Server UI: @@ -131,13 +140,87 @@ Or, The default credentials are; user: admin, password: password and the domain field should be left blank which is defaulted to the ROOT domain. -## Packaging +If you want to contribute your changes, send your [git formatted patch](https://cwiki.apache.org/confluence/display/CLOUDSTACK/Git) to: +https://reviews.apache.org/groups/cloudstack or contact on the developer mailing list. -To create rpms: +## Packaging and Installation - $ mvn -P deps && ./waf rpm +Before packaging, please make sure you go through the "Building" section above. +This section describes packaging and installation. + +### Debian/Ubuntu To create debs: - $ mvn -P deps && dpkg-buildpackage + $ mvn -P deps # -D nonoss, for nonoss as described in the "Building" section above + $ dpkg-buildpackage +All the deb packages will be created in ../$PWD + +To create an apt repo: (assuming appropriate user privileges) + + $ path=/path/to/your/webserver/cloudstack + $ mv ../*.deb $path + $ dpkg-scanpackages $path /dev/null | gzip -9c > $path/Packages.gz + +Configure your system to use your new apt repo: + + $ echo "deb $path ./" >> /etc/apt/sources.list.d/cloudstack.list + +Installation: + +Install needed packages, apt-get upgrade for upgrading: + + $ apt-get update + $ apt-get install cloud-client # management server + $ apt-get install mysql-server # mysql server + $ apt-get install cloud-agent cloud-system-iso # agent (kvm) + $ apt-get install cloud-awsapi # awsapi server + $ apt-get install cloud-usage # usage server + +### RHEL/CentOS + +To create rpms: + + $ mvn -P deps # -D nonoss, for nonoss as described in the "Building" section above + $ ./waf rpm + +All the rpm packages will be create in artifacts/rpmbuild/RPMS/x86_64 + +To create a yum repo: (assuming appropriate user privileges) + + $ path=/path/to/your/webserver/cloudstack + $ cd artifacts/rpmbuild/RPMS/x86_64 + $ mv *.rpm $path + $ createrepo $path + +Configure your system to use your new yum repo, add the following to /etc/yum.repos.d/cloudstack.repo: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://webserver.tld/path/to/repo + enabled=1 + gpgcheck=0 + +Installation: + +Install needed packages: + + $ yum update + $ yum install cloud-client # management server + $ yum install mysql-server # mysql server + $ yum install cloud-agent # agent (kvm) + $ yum install cloud-usage # usage server + +## Notes + +If you will be using Xen as your hypervisor, please download [vhd-util](http://download.cloud.com.s3.amazonaws.com/tools/vhd-util) + +If management server is installed on RHEL/CentOS, then copy vhd-util into: +/usr/lib64/cloud/common/scripts/vm/hypervisor/xenserver/ + +If management server is installed on Ubuntu, then put vhd-util into: +/usr/lib/cloud/common/scripts/vm/hypervisor/xenserver/vhd-util + +Once, you've successfully installed Apache CloudStack you may read the user manuals +and guides which contains technical documentation for Apache CloudStack.