Merge #11
diff --git a/documentation.md b/documentation.md
index 436bfc0..fcc6d82 100644
--- a/documentation.md
+++ b/documentation.md
@@ -1,6 +1,8 @@
---
layout: normal
title: Documentation
++children:
++- { path: documentation/install-on-server.md }
---
## Official User Manual
@@ -10,3 +12,6 @@
- [0.7.0-M1]({{ site.url }}/v/0.7.0-M1) -
Please note that this release was made prior to entering the Apache Incubator,
and therefore it is not endorsed by Apache.
+
+## Server install
+Follow this [guide]({{ site.url }}/documentation/install-on-server.html) to install Brooklyn on a production server.
diff --git a/documentation/increase-entropy.md b/documentation/increase-entropy.md
new file mode 100644
index 0000000..374df20
--- /dev/null
+++ b/documentation/increase-entropy.md
@@ -0,0 +1,30 @@
+---
+title: Increase entropy
+layout: normal
+---
+If you are installing AMP on a virtual machine, you may find it useful to increase the Linux kernel entropy to speed up the ssh connections to the managed entities. You can install and configure `rng-tools` or just use /dev/urandom`.
+
+### Installing rng-tool
+if you are using a RHEL-based OS:
+{% highlight bash %}
+yum -y -q install rng-tools
+echo "EXTRAOPTIONS=\"-r /dev/urandom\"" | cat >> /etc/sysconfig/rngd
+/etc/init.d/rngd start
+{% endhighlight %}
+
+if you are using a Debian-based OS:
+{% highlight bash %}
+apt-get -y install rng-tools
+echo "HRNGDEVICE=/dev/urandom" | cat >> /etc/default/rng-tools
+/etc/init.d/rng-tools start
+{% endhighlight %}
+
+The following links contain further [information for RHEL or CentOS](http://my.itwnik.com/how-to-increase-linux-kernel-entropy/), and [Ubuntu](http://www.howtoforge.com/helping-the-random-number-generator-to-gain-enough-entropy-with-rng-tools-debian-lenny).
+
+### Using /dev/urandom
+You can also just mv /dev/random then create it again linked to /dev/urandom, by issuing the following commands:
+
+{% highlight bash %}
+sudo mv /dev/random /dev/random-real", "sudo ln -s /dev/urandom /dev/random"
+{% endhighlight %}
+
diff --git a/documentation/install-on-server.md b/documentation/install-on-server.md
new file mode 100644
index 0000000..2c723b1
--- /dev/null
+++ b/documentation/install-on-server.md
@@ -0,0 +1,123 @@
+---
+layout: normal
+title: Install Apache Brooklyn® on a server
+---
+Here we present two *alternatives* to install Brooklyn:
+
+- [Running the *installation script*](#script)
+- [Manual installation](#manual)
+
+## <a id="script"></a> Running the installation script
+There is a simple bash script available to help with the installation process.
+
+#### Script prerequisites
+The script assumes that the server is a recent *RHEL/CentOS 6.x Linux* or *Ubuntu 12.04* installation, but other Linux variants have been tested successfully.
+
+The script will install Java 7 and other required packages if they are not present. You must have root access over [passwordless SSH]({{ site.url }}/documentation/passwordless-ssh.html) to install brooklyn, but the service runs as an ordinary user once installed.
+
+To manage the brooklyn service you must also be able to connect to port 8081 remotely.
+
+Once the above prerequisites are satisfied, you should be able to run successfully:
+{% highlight bash %}
+$ curl -o brooklyn-install.sh http://git.io/GzkOKQ
+$ chmod +x ./brooklyn-install.sh
+$ ./brooklyn-install.sh -s -r <your-server-ip>
+{% endhighlight %}
+
+## <a id="manual"></a> Manual installation
+
+1. [Set up the prerequisites](#prerequisites)
+1. [Download Brooklyn](#download)
+1. [Configuring brooklyn.properties](#configuring-properties)
+1. [Configuring catalog.xml](#configuring-catalog)
+1. [Test the installation](#confirm)
+
+### <a id="prerequisites"></a>Set up the prerequisites
+
+Before installing Apache Brooklyn, you will need to configure the host as follows.
+
+* install Java JRE or SDK (version 6 or later)
+* install [SSH key]({{ site.url }}/documentation//ssh-key.html), if not available.
+* enable [passwordless ssh login]({{ site.url }}/documentation/passwordless-ssh.html).
+* create a `~/.brooklyn` directory on the host with `$ mkdir ~/.brooklyn`
+* Check your iptables service, and if enabled, make sure that it accepts all incoming connections to 8443+ ports.
+* [optional] Increase [linux kernel entropy]({{ site.url }}/documentation//increase-entropy.html) for faster ssh connections.
+
+## <a id="download"></a>Download Brooklyn
+
+Download the [Brooklyn distribution]({{ site.data.brooklyn.url.dist.tgz }}) and expand it to your home directory ( `~/` ), or in a location of your choice. Other [download options]({{site.url}}/download.html) are available.
+
+{% if brooklyn_version contains 'SNAPSHOT' %}
+Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
+{% else %}
+Expand the `tar.gz` archive:
+{% endif %}
+
+{% if brooklyn_version contains 'SNAPSHOT' %}
+{% highlight bash %}
+$ tar -zxf brooklyn-dist-{{ site.data.brooklyn.version }}-timestamp-dist.tar.gz
+{% endhighlight %}
+{% else %}
+{% highlight bash %}
+$ tar -zxf brooklyn-dist-{{ site.data.brooklyn.version }}-dist.tar.gz
+{% endhighlight %}
+{% endif %}
+
+This will create a `brooklyn-{{ site.data.brooklyn.version }}` folder.
+
+Let's setup some paths for easy commands.
+
+{% highlight bash %}
+$ cd brooklyn-{{ site.data.brooklyn.version }}
+$ BROOKLYN_DIR="$(pwd)"
+$ export PATH=$PATH:$BROOKLYN_DIR/bin/
+{% endhighlight %}
+
+## <a id="configuring-properties"></a>Configuring brooklyn.properties
+Brooklyn deploys applications to Locations. *Locations* can be clouds, machines with fixed IPs or localhost (for testing).
+
+By default Brooklyn loads configuration parameters (including credentials for any cloud accounts) from
+
+`~/.brooklyn/brooklyn.properties`
+
+The `brooklyn.properties` is the main configuration file for deployment locations. Contains the connection details and credentials for all public or on-premises cloud providers, as well as controlling some application startup and security options.
+
+Create a `.brooklyn` folder in your home directory and download the template [brooklyn.properties]({{ site.url }}/brooklyn.properties) to that folder.
+
+{% highlight bash %}
+$ mkdir -p ~/.brooklyn
+$ curl -o ~/.brooklyn/brooklyn.properties http://brooklyncentral.github.io/use/guide/quickstart/brooklyn.properties
+$ chmod 600 ~/.brooklyn/brooklyn.properties
+{% endhighlight %}
+
+You may need to edit `~/.brooklyn/brooklyn.properties` to ensure that brooklyn can access cloud locations for application deployment.
+
+## <a id="configuring-catalog"></a>Configuring catalog.xml
+By default Brooklyn loads the catalog of available application components and services from
+`~/.brooklyn/catalog.xml`.
+
+{% highlight bash %}
+$ curl -o ~/.brooklyn/catalog.xml \
+http://brooklyncentral.github.io/use/guide/quickstart/catalog.xml
+{% endhighlight %}
+
+The `catalog.xml` is the application blueprint catalog. The above example file contains some blueprints which will be automatically downloaded from the web if you run them.
+
+You may need to edit `~/.brooklyn/catalog.xml` to update links to any resources for download.
+
+## <a id="confirm"></a>Confirm installation
+We can do a quick test drive by launching Brooklyn:
+
+{% highlight bash %}
+$ brooklyn launch
+{% endhighlight %}
+
+Brooklyn will output the address of the management interface:
+
+{% highlight bash %}
+INFO Starting brooklyn web-console on loopback interface because no security config is set
+
+INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []
+{% endhighlight %}
+
+Stop Brooklyn with ctrl-c.
diff --git a/documentation/passwordless-ssh.md b/documentation/passwordless-ssh.md
new file mode 100644
index 0000000..63ddbd5
--- /dev/null
+++ b/documentation/passwordless-ssh.md
@@ -0,0 +1,29 @@
+---
+title: Passwordless SSH login
+layout: normal
+---
+To enable passwordless SSH login to a *nix server, first you will need a pair of keys. If you don't already have a keypair generated you'll first of all need to create one.
+To generate a new keypair you run the following command:
+
+ your-user@host1:~$ ssh-keygen -t rsa
+
+This will prompt you for a location to save the keys, and a pass-phrase:
+
+ Generating public/private rsa key pair.
+ Enter file in which to save the key (/home/skx/.ssh/id_rsa):
+ Enter passphrase (empty for no passphrase):
+ Enter same passphrase again:
+ Your identification has been saved in /home/skx/.ssh/id_rsa.
+ Your public key has been saved in /home/skx/.ssh/id_rsa.pub.
+
+Then, assuming that you want to enable passwordless SSH login to the `host2` server from `host1` with the `id_rsa` and `id_rsa.pub` files you've just generated you should run the following command:
+
+ your-user@host1:~$ ssh-copy-id -i ~/.ssh/id_rsa.pub username@host2
+
+If `host1` doesn't have `ssh-copy-id` installed, you can either install `ssh-copy-id` or manually copy the `id_rsa.pub` key to the `host2` by issuing the following commands:
+
+ host1# cat ~/.ssh/id_rsa.pub | ssh user@host2 'cat >> .ssh/authorized_keys'
+
+or if you need to make a `.ssh` directory on `host2`
+
+ host1#cat ~/.ssh/id_rsa.pub | ssh user@host2 'mkdir .ssh; chmod 700 .ssh; cat >> .ssh/authorized_keys; chmod 644 .ssh/authorized_keys'
diff --git a/documentation/ssh-key.md b/documentation/ssh-key.md
new file mode 100644
index 0000000..1dc2690
--- /dev/null
+++ b/documentation/ssh-key.md
@@ -0,0 +1,9 @@
+---
+title: SSH keys
+layout: normal
+---
+Brooklyn requires an SSH key, which will be used to connect to cloud VMs. By default Brooklyn will look for SSH keys named `~/.ssh/id_rsa` or `~/.ssh/id_dsa`. If you do not already have an SSH key installed, create a new key.
+
+{% highlight bash %}
+$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
+{% endhighlight %}
\ No newline at end of file
diff --git a/quickstart/policies-and-catalogs.md b/quickstart/policies-and-catalogs.md
index 7e6723f..bfeb231 100644
--- a/quickstart/policies-and-catalogs.md
+++ b/quickstart/policies-and-catalogs.md
@@ -1,5 +1,5 @@
---
-title: Getting Started - Policies and Catalogs
+title: Policies and Catalogs
layout: normal
---
