adding content on building packages from source
Project: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/commit/512501e5 Tree: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/tree/512501e5 Diff: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/diff/512501e5 Branch: refs/heads/master Commit: 512501e58a55098f85efa57c6f6cfa1460a3d1df Parents: 59b77a9 Author: David Nalley <[email protected]> Authored: Wed Oct 17 02:20:17 2012 -0400 Committer: David Nalley <[email protected]> Committed: Wed Oct 17 02:20:17 2012 -0400 ---------------------------------------------------------------------- docs/en-US/Installation_Guide.xml | 1 + docs/en-US/build-deb.xml | 60 +++++++++++++++++++++++ docs/en-US/build-rpm.xml | 82 ++++++++++++++++++++++++++++++++ docs/en-US/extracting-source.xml | 36 ++++++++++++++ docs/en-US/getting-release.xml | 63 ++++++++++++++++++++++++ docs/en-US/source-prereqs.xml | 42 ++++++++++++++++ docs/en-US/source.xml | 20 ++++++-- docs/en-US/verifying-source.xml | 82 ++++++++++++++++++++++++++++++++ 8 files changed, 381 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/Installation_Guide.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/Installation_Guide.xml b/docs/en-US/Installation_Guide.xml index c945020..bdc3b8e 100644 --- a/docs/en-US/Installation_Guide.xml +++ b/docs/en-US/Installation_Guide.xml @@ -46,6 +46,7 @@ </bookinfo> <xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="cloud-infrastructure-concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="source.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="ui.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="provisioning-steps.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/build-deb.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/build-deb.xml b/docs/en-US/build-deb.xml new file mode 100644 index 0000000..0fe3d90 --- /dev/null +++ b/docs/en-US/build-deb.xml @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +<section id="sect-source-builddebs"> + <title>Building DEB packages</title> + <para> + In addition to the bootstrap dependencies, you'll also need to install + a few other dependencies by issuing the following commands: + <programlisting><prompt>#</prompt> <command>apt-get</command> update</programlisting> + <programlisting><prompt>$</prompt> <command>apt-get</command> install debhelper openjdk-6-jdk tomcat6 libws-commons-util-java genisoimage python-mysqldb</programlisting> + </para> + <para> + While we have defined, and you have presumably already installed the + bootstrap prerequisites, there are a number of build time prerequisites + that need to be resolved. &PRODUCT; uses maven for dependency resolution. + You can resolve the buildtime depdencies for CloudStack by running the + following command: + <programlisting><prompt>$</prompt> <command>mvn</command> -P deps</programlisting> + </para> + <para> + Now that we have resolved the dependencies we can move on to building &PRODUCT; + and packaging them into DEBs by issuing the following command. + <programlisting><prompt>#</prompt> <command>dpkg-buildpackage</command></programlisting> + </para> + + <section id="sect-source-builddebs-repo"> + <title>Setting up an APT repo</title> + <para>TBD</para> + </section> + <section id="sect-source-builddebs-repo2"> + <title>Configuring your machines to use the APT repository</title> + <para> + Now that we have created the repository, you need to configure your machine + to make use of the APT repository. We do that by issuing the following commands: + <programlisting><prompt>$</prompt> <command>echo</command> "deb <replaceable>http://url.to/apt/repo</replaceable> $(lsb_release -s -c) 4.0" > <filename>/etc/apt/sources.list.d/cloudstack.list</filename></programlisting> + <programlisting><prompt>#</prompt> <command>apt-get</command> update </programlisting> + </para> + </section> +</section> http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/build-rpm.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/build-rpm.xml b/docs/en-US/build-rpm.xml new file mode 100644 index 0000000..e983aba --- /dev/null +++ b/docs/en-US/build-rpm.xml @@ -0,0 +1,82 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +<section id="sect-source-buildrpm"> + <title>Building RPMs</title> + <para> + While we have defined, and you have presumably already installed the + bootstrap prerequisites, there are a number of build time prerequisites + that need to be resolved. &PRODUCT; uses maven for dependency resolution. + You can resolve the buildtime depdencies for CloudStack by running the + following command: + <programlisting><prompt>$</prompt> <command>mvn</command> -P deps</programlisting> + </para> + <para> + Now that we have resolved the dependencies we can move on to building &PRODUCT; + and packaging them into RPMs by issuing the following command. + <programlisting><prompt>$</prompt> <command>./waf</command> rpm</programlisting> + </para> + <para> + Once this completes, you should find assembled RPMs in + <filename>artifacts/rpmbuild/RPMS/x86_64</filename> + </para> + <section id="sect-source-buildrpm-repo"> + <title>Creating a yum repo</title> + <para> + While RPMs is an ideal packaging format - it's most easily consumed from + yum repositories over a network. We'll move into the directory with the + newly created RPMs by issuing the following command: + <programlisting><prompt>$</prompt> <command>cd</command> artifacts/rpmbuild/RPMS/x86_64</programlisting> + </para> + <para> + Next we'll issue a command to create the repository metadata by + issuing the following command: + <programlisting><prompt>$</prompt> <command>createrepo</command> ./</programlisting> + </para> + <para> + The files and directories within our current working directory can now + be uploaded to a web server and serve as a yum repository + </para> + </section> + <section id="sect-source-buildrpm-repo2"> + <title>Configuring your systems to use your new yum repository</title> + <para> + Now that your yum repository is populated with RPMs and metadata + we need to configure our machines that need to install CloudStack. + We will create a file at <filename>/etc/yum.repos.d/cloudstack.repo</filename> + with the following content: +<programlisting> +[apache-cloudstack] +name=Apache CloudStack +baseurl=http://<replaceable>webserver.tld/path/to/repo</replaceable> +enabled=1 +gpgcheck=0 +</programlisting> + </para> + <para> + Completing this step will allow you to easily install CloudStack on a number of + machines across the network. + </para> + </section> +</section> http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/extracting-source.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/extracting-source.xml b/docs/en-US/extracting-source.xml new file mode 100644 index 0000000..97a40b6 --- /dev/null +++ b/docs/en-US/extracting-source.xml @@ -0,0 +1,36 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +<section id="sect-source-extract"> + <title>Extracting source</title> + <para> + Extracting the &PRODUCT; release is relatively simple and can be done + with a single command as follows: + <programlisting><prompt>$</prompt> <command>tar</command> -jxvf apache-cloudstack-4.0.0-incubating-src.tar.bz2</programlisting> + </para> + <para> + You can now move into the directory: + <programlisting><prompt>$</prompt> <command>cd</command> ./apache-cloudstack-4.0.0-incubating-src</programlisting> + </para> +</section> http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/getting-release.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/getting-release.xml b/docs/en-US/getting-release.xml new file mode 100644 index 0000000..5ed6ac1 --- /dev/null +++ b/docs/en-US/getting-release.xml @@ -0,0 +1,63 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +<section id="sect-source-gettingrelease"> + <title>Getting the release</title> + <para> + You can download the official &PRODUCT; 4.0.0 release from the + <ulink url="http://incubator.apache.org/cloudstack/downloads.html";> + Apache CloudStack project download page</ulink>. + </para> + <para> + You'll notice several links under the 'Latest release' section. + </para> + <orderedlist> + <listitem> + <para> + <ulink url="http://www.apache.org/dyn/closer.cgi/dist/incubator/cloudstack/releases/4.0.0-incubating/apache-cloudstack-4.0.0-incubating-src.tar.bz2";> + apache-cloudstack-4.0.0-incubating-src.tar.bz2</ulink> + - This is the link to the release itself. + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.apache.org/dist/incubator/cloudstack/releases/4.0.0-incubating/apache-cloudstack-4.0.0-incubating-src.tar.bz2.asc";>PGP</ulink> + - This is a detached cryptographic signature that can be used to help + verify the authenticity of the release. + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.apache.org/dist/incubator/cloudstack/releases/4.0.0-incubating/apache-cloudstack-4.0.0-incubating-src.tar.bz2.md5";>MD5</ulink> + - An MD5 hash of the release to aid in verify the validity of the release download. + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.apache.org/dist/incubator/cloudstack/releases/4.0.0-incubating/apache-cloudstack-4.0.0-incubating-src.tar.bz2.sha";>SHA512</ulink> + - A SHA512 hash of the release to aid in verify the validity of the release download. + </para> + </listitem> + </orderedlist> +</section> http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/source-prereqs.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/source-prereqs.xml b/docs/en-US/source-prereqs.xml new file mode 100644 index 0000000..6c2bc2a --- /dev/null +++ b/docs/en-US/source-prereqs.xml @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +<section id="sect-source-prereq"> + <title>Prerequisites for building Apache CloudStack</title> + <para> + There are a number of prerequisites needed to build &PRODUCT;. This + document assumes compilation on a Linux system that uses RPMs or DEBs + for package management. + </para> + <para> + The minimum bootstrapped prerequisites for building &PRODUCT; includes + the following: + <orderedlist> + <listitem><para>ant</para></listitem> + <listitem><para>maven (version 3)</para></listitem> + <listitem><para>Java (Java 6/OpenJDK 1.6) </para></listitem> + <listitem><para>rpmbuild or dpkg-dev</para></listitem> + </orderedlist> + </para> +</section> http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/source.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/source.xml b/docs/en-US/source.xml index ffa3d0c..3cb4af2 100644 --- a/docs/en-US/source.xml +++ b/docs/en-US/source.xml @@ -1,5 +1,5 @@ <?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ <!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> %BOOK_ENTITIES; ]> @@ -22,16 +22,26 @@ under the License. --> -<section id="sect-source"> +<chapter id="sect-source"> <title>Building from Source</title> <para>The official &PRODUCT; release is always in source code form. While there may exist convenience binaries in various forms from a number of places, the source is the canonical release will be source. In this document we'll cover acquiring the source release, building that into binary, deployable packages. </para> + <para> + While building and deploying directly from source is certainly possible, the reality + of Infrastructure-as-a-Service cloud computing implies a need to deploy packages on + a potentially large number of systems, which RPMs and DEBs fill nicely. + </para> + <para> + Building and deploying directly from source is thus outside the scope of this + document, but is documented in the INSTALL.md file in the release. + </para> <xi:include href="getting-release.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="verifying-source.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="source-prereqs.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> - <xi:include href="build-deb-packages" xmlns:xi="http://www.w3.org/2001/XInclude"; /> - <xi:include href="build-rpm-packages" xmlns:xi="http://www.w3.org/2001/XInclude"; /> -</section> + <xi:include href="extracting-source.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="build-deb.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="build-rpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> +</chapter> http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/512501e5/docs/en-US/verifying-source.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/verifying-source.xml b/docs/en-US/verifying-source.xml new file mode 100644 index 0000000..05b54ec --- /dev/null +++ b/docs/en-US/verifying-source.xml @@ -0,0 +1,82 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +<section id="sect-source-verify"> + <title>Verifying the downloaded release</title> + <para> + There are a number of mechanisms to check the authenticity and validity of a + downloaded release. + </para> + <section id="sect-source-verify-keys"> + <title>Getting the KEYS</title> + <para> + To enable you to verify the GPG signature, you will need to download the + <ulink url="http://www.apache.org/dist/dev/incubator/cloudstack/KEYS";>KEYS</ulink> + file. + </para> + <para> + You next need to import those keys, which you can do by running the following command: + <programlisting><prompt>#</prompt> <command>gpg</command> --import KEYS</programlisting> + </para> + </section> + <section id="sect-source-verify-gpg"> + <title>GPG</title> + <para> + The &PRODUCT; project provides a detached GPG signature of the release. + To check the signature, run the following command: + <programlisting><prompt>$</prompt> <command>gpg</command> --verify apache-cloudstack-4.0.0-incubating-src.tar.bz2.asc</programlisting> + </para> + <para> + If the signature is valid you will see a line of output that contains 'Good signature'. + </para> + </section> + <section id="sect-source-verify-md5"> + <title>MD5</title> + <para> + In addition to the cryptographic signature, the &PRODUCT; provides a number + of cryptographic hashes to aid in assurance of validity of the downloaded + release. You can verify this hash by executing the following command: + <programlisting><prompt>$</prompt> <command>gpg</command> --print-md MD5 apache-cloudstack-4.0.0-incubating-src.tar.bz2 | <command>diff</command> - apache-cloudstack-4.0.0-incubating-src.tar.bz2.md5</programlisting> + </para> + <para> + If this successfully completes you should see no output. If there is any output from them, + then there is a difference between the hash you generated locally and the hash that has been + pulled from the server. + </para> + </section> + <section id="sect-source-verify-sha512"> + <title>SHA512</title> + <para> + In addition to the MD5 hash, the &PRODUCT; project provides a SHA512 + cryptographic hash to aid in assurance of the validity of the downloaded + release. You can verify this hash by executing the following command: + <programlisting><prompt>$</prompt> <command>gpg</command> --print-md SHA512 apache-cloudstack-4.0.0-incubating-src.tar.bz2 | <command>diff</command> - apache-cloudstack-4.0.0-incubating-src.tar.bz2.sha</programlisting> + </para> + <para> + If this command successfully completes you should see no output. If there is any output from them, + then there is a difference between the hash you generated locally and the hash that has been + pulled from the server. + </para> + </section> +</section>
