brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [08/13] incubator-brooklyn git commit: lots more tidy-up of docs, esp in ops
Date Tue, 20 Jan 2015 16:12:26 GMT
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/yaml/configuring-vms.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/configuring-vms.md b/docs/guide/yaml/configuring-vms.md
index 709746c..97fb9d0 100644
--- a/docs/guide/yaml/configuring-vms.md
+++ b/docs/guide/yaml/configuring-vms.md
@@ -28,4 +28,4 @@ including:
 * `machineCreateAttempts` (for dodgy clouds, and they nearly all fail occasionally!) 
 * and things like `imageId` and `userMetadata` and disk and networking options (e.g. `autoAssignFloatingIp`
for private clouds)
 
-For more information, see the javadoc on `JcloudsLocationConfig`.
+For more information, see [Operations: Locations](../ops/locations/).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/yaml/creating-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/creating-yaml.md b/docs/guide/yaml/creating-yaml.md
index 6141a18..8c6b31f 100644
--- a/docs/guide/yaml/creating-yaml.md
+++ b/docs/guide/yaml/creating-yaml.md
@@ -25,7 +25,7 @@ Here's a very simple YAML blueprint plan, to explain the structure:
 * The `name` is just for the benefit of us humans.
 
 * The `location` specifies where this should be deployed.
-  If you've [set up passwordless localhost SSH access](setting-locations.html#localhost)

+  If you've [set up passwordless localhost SSH access](../ops/locations/#localhost) 
   you can use `localhost` as above, but if not, just wait ten seconds for the next example.
   
 * The `services` block takes a list of the typed services we want to deploy.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/yaml/multiple-services.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/multiple-services.md b/docs/guide/yaml/multiple-services.md
index a6816e6..0f443dd 100644
--- a/docs/guide/yaml/multiple-services.md
+++ b/docs/guide/yaml/multiple-services.md
@@ -1,10 +1,44 @@
 ---
 title: Multiple Services and Dependency Injection
 layout: website-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
 ---
 
+We've seen the configuration of machines and how to build up clusters.
+Now let's return to our app-server example and explore how more interesting
+services can be configured, composed, and combined.
+
+
+### Service Configuration
+
+We'll begin by using more key-value pairs to configure the JBoss server to run a real app:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-configured.yaml %}
+{% endhighlight %}
+
+(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent
examples.)
+
+When this is deployed, you can see management information in the Brooklyn Web Console,
+including a link to the deployed application (downloaded to the target machine from the `hello-world`
URL),
+running on port 8080.
+
+**Tip**:  If port 8080 might be in use, you can specify `8080+` to take the first available
port >= 8080;
+the actual port will be reported as a sensor by Brooklyn.
+
+It's also worth indicating an alternate, more formal syntax.
+Not all configuration on entities is supported at the top level of the service specification
+(only those which are defined as "flags" in the underlying blueprint,
+e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`).
+All configuration has a formal qualified name, and this can be supplied even where flags
or config keys are not
+explicitly defined, by placing it into a `brooklyn.config` section:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-configured-in-config.yaml %}
+{% endhighlight %}
+
+
+### Multiple Services
+
 If you explored the `hello-world-sql` application we just deployed, 
 you'll have noticed it tries to access a database.
 And it fails, because we have not set one up.  Let's do that now:
@@ -45,7 +79,6 @@ At that point the URL is injected, first passing it through `formatString`
 to include the credentials for the database (which are defined in the database creation script).
 
 
-
 ### An Aside: Substitutability
 
 Don't like JBoss?  Is there something about Maria?

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/yaml/mutlitple-services.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/mutlitple-services.md b/docs/guide/yaml/mutlitple-services.md
deleted file mode 100644
index 24f7b1d..0000000
--- a/docs/guide/yaml/mutlitple-services.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: Multiple Services and Dependency Injection
-layout: website-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-We've seen the configuration of machines and how to build up clusters.
-Now let's return to our app-server example and explore how more interesting
-services can be configured, composed, and combined.
-
-Also note there are some good overview materials [here]({{site.path.guide}}//use/guide/defining-applications/basic-concepts.html)
-covering clusters, sensors, effectors and more, 
-if you're the kind of person who likes to learn more about concepts before seeing them in
action.
-
-
-### Service Configuration
-
-We'll begin by using more key-value pairs to configure the JBoss server to run a real app:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-configured.yaml %}
-{% endhighlight %}
-
-(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent
examples.)
-
-When this is deployed, you can see management information in the Brooklyn Web Console,
-including a link to the deployed application (downloaded to the target machine from the `hello-world`
URL),
-running on port 8080.
-
-**Top tip**:  If port 8080 might be in use, you can specify `8080+` to take the first available
port >= 8080;
-the actual port will be reported as a sensor by Brooklyn.
-
-It's also worth indicating an alternate, more formal syntax.
-Not all configuration on entities is supported at the top level of the service specification
-(only those which are defined as "flags" in the underlying blueprint,
-e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`).
-All configuration has a formal qualified name, and this can be supplied even where flags
or config keys are not
-explicitly defined, by placing it into a `brooklyn.config` section:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-configured-in-config.yaml %}
-{% endhighlight %}
-
-If you explored the `hello-world-sql` application we just deployed, 
-you'll have noticed it tries to access a database.
-And it fails, because we have not set one up.  Let's do that now:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-w-db.yaml %}
-{% endhighlight %}
-
-Here there are a few things going on:
-
-* We've added a second service, which will be the database;
-  you'll note the database has been configured to run a custom setup script
-* We've injected the URL of the second service into the appserver as a Java system property
-  (so our app knows where to find the database) 
-
-**Caution: Be careful if you write your YAML in an editor which attempts to put "smart-quotes"
in.
-All quote characters must be plain ASCII, not fancy left-double-quotes and right-double-quotes!**
-
-There are as many ways to do dependency injection as there are developers,
-it sometimes seems; our aim in Brooklyn is not to say this has to be done one way,
-but to support the various mechanisms people might need to do, for whatever reasons.
-(We each have our opinions about what works well, of course;
-the one thing we do want to call out is that being able to dynamically update
-the injection is useful in a modern agile application -- so we are definitively **not**
-recommending this Java system property approach ... but it is an easy one to demo!)
-
-The way the dependency injection works is again by using the `$brooklyn:` DSL,
-this time referring to the `component("db")` (looked up by the `id` field on our DB component),
-and then to a sensor emitted by that component.
-All the database entities emit a `database.url` sensor when they are up and running;
-the `attributeWhenReady` DSL method will store a pointer to that sensor (a Java Future under
the covers)
-in the Java system properties map which the JBoss entity reads at launch time, blocking if
needed.
-
-This means that the deployment occurs in parallel, and if the database comes up first,
-there is no blocking; but if the JBoss entity completes its installation and 
-downloading the WAR, it will wait for the database before it launches.
-At that point the URL is injected, first passing it through `formatString`
-to include the credentials for the database (which are defined in the database creation script).
-
-
-
-### An Aside: Substitutability
-
-Don't like JBoss?  Is there something about Maria?
-One of the modular principles we follow in Brooklyn is substitutability:
-in many cases, the config keys, sensors, and effectors are defined
-in superclasses and are portable across multiple implementations.
-
-Here's an example deploying the same application but with different flavors of the components:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-w-db-other-flavor.yaml %}
-{% endhighlight %}
-
-We've also brought in the `provisioning.properties` from the VM example earlier
-so our database has 8GB RAM.
-Any of those properties, including `imageId` and `user`, can be defined on a per-entity basis.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/yaml/setting-locations.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/setting-locations.md b/docs/guide/yaml/setting-locations.md
index 4924557..7f5dfc4 100644
--- a/docs/guide/yaml/setting-locations.md
+++ b/docs/guide/yaml/setting-locations.md
@@ -32,13 +32,12 @@ depending on the blueprint):
 {% readj example_yaml/simple-appserver-with-location-byon.yaml %}
 {% endhighlight %}
 
-You'll also note in this example that we've used JSON-style notation in the second `location`
block.
+Note in this example that we've used JSON-style notation in the second `location` block.
 YAML supports this, and sometimes that makes more readable plans.
-(Although in this case a simple `location: localhost` is equivalent and even more succinct,
but this is a tutorial.)
-
-For more information see the Locations section of the [YAML reference](yaml-reference.html)

-and in the [Operations]({{ site.path.guide }}/ops/locations) section of the User Guide.
-Another good reference is the [template brooklyn.properties]({{ brooklyn_properties_url_path
}}),
-which if you install in `~/.brooklyn/brooklyn.properties` and edit with your credentials,
 
-allows you to refer to clouds simply as `location: jclouds:aws-ec2:eu-west-1` or
-set up "named locations" you can use as `location: named:my_cloudstack`.
+(Although in this case a simple `location: localhost` is equivalent and even more succinct,

+but this is a tutorial.)
+
+For more information see the [Operations: Locations]({{ site.path.guide }}/ops/locations)
section of the User Guide.
+This includes support for defining locations externally in a [brooklyn.properties]({{ brooklyn_properties_url_path
}}) file,
+after which you can deploy to clouds or bring-your-own-nodes
+simply as `location: jclouds:aws-ec2:eu-west-1` or `location: named:my_cloudstack`.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/style/css/_basic.scss
----------------------------------------------------------------------
diff --git a/docs/style/css/_basic.scss b/docs/style/css/_basic.scss
index 2f5a989..ff0f060 100644
--- a/docs/style/css/_basic.scss
+++ b/docs/style/css/_basic.scss
@@ -20,12 +20,6 @@ img {border: 0;}
 a {color: $a_color;}
 a:hover {text-decoration: none; color: $a_hover_color;}
 
-/* Offset link anchors so they are not hidden by the header */
-a[id]:empty, a[name]:empty {
-    padding-top: 60px;
-    margin-top: -60px;
-    display: block;
-}
 .dropdown-menu > li > a {
   font-weight: 300;
 }

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/style/css/_main_container.scss
----------------------------------------------------------------------
diff --git a/docs/style/css/_main_container.scss b/docs/style/css/_main_container.scss
index 09e2634..0ce2fcc 100644
--- a/docs/style/css/_main_container.scss
+++ b/docs/style/css/_main_container.scss
@@ -10,23 +10,29 @@
 /* HEADER LINKS 
    ----------------------------------------------------------------------- */
 
-/* this causes jumps to anchors to show the anchor below the navbar */
-#content_container { h1, h2, h3, h4, h5, h6 {
-    margin-top: -64px;
-    padding-top: 64px;
-}}
-
 #content_container h1 {
   max-width: 95%;
   font-variant: normal;
   margin-top: -16px;
   padding-bottom: 6px;
+  margin-top: 64px;
   margin-bottom: 24px;
   border-bottom: 1px dotted $gray_aa;
   font-weight: 300;
   font-size: 36px;
   text-transform: uppercase;
 }
+h4, h5, h6 {
+  margin-top: 20px;
+  margin-bottom: 8px;
+}
+h5 {
+  font-size: 18px;
+  font-weight: 300;
+}
+h6 {
+  font-size: 16px;
+}
 
 /* headings get a tooltip showing the permalink URL, a la github jekyll */
 /* install subset of font-awesome */

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/community/index.md
----------------------------------------------------------------------
diff --git a/docs/website/community/index.md b/docs/website/community/index.md
index 6ba4000..29fe46c 100644
--- a/docs/website/community/index.md
+++ b/docs/website/community/index.md
@@ -60,7 +60,7 @@ Find us on `#brooklyncentral` on Freenode, or click below for more information.
 
 <div class="panel panel-default">
   <div class="panel-heading" markdown="1">
-#### [Developer community](../developers/index.md)
+#### [Developer community](../developers/)
   </div>
   <div class="panel-body" markdown="1">
 Want to contribute code to our project? Head over to our developer's section. Warning, bleeding
edge code ahead!

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/developers/index.md
----------------------------------------------------------------------
diff --git a/docs/website/developers/index.md b/docs/website/developers/index.md
index 2edae18..1d3ac4a 100644
--- a/docs/website/developers/index.md
+++ b/docs/website/developers/index.md
@@ -31,7 +31,7 @@ and are comfortable doing so.
 
 Firstly, please see our [community resources](../community/index.html), in particular:
 
-- [Mailing lists](../community/mailist-lists.html)
+- [Mailing lists](../community/mailing-lists.html)
 - [IRC channel](../community/irc.html)
 - [JIRA for bug tracking](https://issues.apache.org/jira/browse/BROOKLYN)
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/documentation/index.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/index.md b/docs/website/documentation/index.md
index 13f4d3d..03f96b7 100644
--- a/docs/website/documentation/index.md
+++ b/docs/website/documentation/index.md
@@ -4,13 +4,14 @@ title: Documentation
 children:
 - /guide/
 - /guide/dev/
-- faq.md
 - other-docs.md
 ---
 
 {% comment %}
-This is redundant with versions page.  Link to versions page?  List more things including
other docs?
+TODO This is redundant with versions page.  Link to versions page?  List more things including
other docs?
 Basically make this page pretty...
+
+TODO also add FAQ
 {% endcomment %}
 
 ## Official User Guide
@@ -24,8 +25,10 @@ Our main user manual is organised by release version. Please pick the version
th
   Please note that this release was made prior to entering the Apache Incubator,
   and therefore it is not endorsed by Apache.
 
-From the links above you can also access the Developer Guide for the relevant versions.
+- [Other versions]({{ site.path.website }}/meta/versions.html)
+
 
 ## Other Docs
 
-Many other mini-docs are available [here](other-docs.html).
+Other mini-docs are available [here](other-docs.html),
+or see the [Learn More]({{ site.path.website }}/learnmore) section of the site.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/documentation/install-on-server.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/install-on-server.md b/docs/website/documentation/install-on-server.md
index aeb44bf..defef7e 100644
--- a/docs/website/documentation/install-on-server.md
+++ b/docs/website/documentation/install-on-server.md
@@ -16,7 +16,9 @@ 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.path.website }}/documentation/passwordless-ssh.html)
to install brooklyn, but the service runs as an ordinary user once installed. 
+The script will install Java 7 and other required packages if they are not present. 
+You must have root access over [passwordless SSH]({{ site.path.guide }}/ops/locations/ssh-keys.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.
 
@@ -37,18 +39,19 @@ $ ./brooklyn-install.sh -s -r <your-server-ip>
 
 ### <a id="prerequisites"></a>Set up the prerequisites
 
-Before installing Apache Brooklyn, you will need to configure the host as follows. 
+Before installing Apache Brooklyn, it is recommented to configure the host as follows. 
 
 * install Java JRE or SDK (version 6 or later)
-* install [SSH key]({{ site.path.website }}/documentation//ssh-key.html), if not available.
-* enable [passwordless ssh login]({{ site.path.website }}/documentation/passwordless-ssh.html).
+* install an [SSH key]({{ site.path.guide }}/ops/locations/ssh-keys.html), if not available
+* enable [passwordless ssh login]({{ site.path.guide }}/ops/locations/ssh-keys.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.path.website }}/documentation//increase-entropy.html)
for faster ssh connections.
+* check your `iptables` or other firewall service, making sure that incoming connections
on port 8443 is not blocked
+* check that the [linux kernel entropy](increase-entropy.html) is sufficient
+
 
 ## <a id="download"></a>Download Brooklyn
 
-Download Brooklyn and obtain a binary build as described on [the download page]({{site.path.website}}/download.html).
+Download Brooklyn and obtain a binary build as described on [the download page]({{site.path.website}}/download/).
 
 {% if brooklyn_version contains 'SNAPSHOT' %}
 Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be
slightly different):

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/documentation/passwordless-ssh.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/passwordless-ssh.md b/docs/website/documentation/passwordless-ssh.md
deleted file mode 100644
index 6cd3e5a..0000000
--- a/docs/website/documentation/passwordless-ssh.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: Passwordless SSH login
-layout: website-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'

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/documentation/ssh-key.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/ssh-key.md b/docs/website/documentation/ssh-key.md
deleted file mode 100644
index 9082af1..0000000
--- a/docs/website/documentation/ssh-key.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-title: SSH keys
-layout: website-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 %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/documentation/todo.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/todo.md b/docs/website/documentation/todo.md
deleted file mode 100644
index 724cb8c..0000000
--- a/docs/website/documentation/todo.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: TODO
-layout: website-normal
----
-
-TODO
-

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/learnmore/blueprint-tour.md
----------------------------------------------------------------------
diff --git a/docs/website/learnmore/blueprint-tour.md b/docs/website/learnmore/blueprint-tour.md
index 04ce5d2..e13fcd8 100644
--- a/docs/website/learnmore/blueprint-tour.md
+++ b/docs/website/learnmore/blueprint-tour.md
@@ -23,7 +23,7 @@ title_in_menu: Blueprint Tour
             optionally adding a version and other metadata.
             The format is YAML -- a human-friendly extension to JSON --
             following the  
-            <a href="{{ site.path.guide }}/learnmore/theory.html">CAMP</a> standard.
+            <a href="{{ site.path.website }}/learnmore/theory.html#standards">CAMP</a>
standard.
           </p><p>
             Treat it like source code: use comments, version control it, test it with CI.
         </p></div>

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/website/learnmore/theory.md
----------------------------------------------------------------------
diff --git a/docs/website/learnmore/theory.md b/docs/website/learnmore/theory.md
index 4f0e6a8..eddb2f8 100644
--- a/docs/website/learnmore/theory.md
+++ b/docs/website/learnmore/theory.md
@@ -122,9 +122,8 @@ managing complex software to be codified as part of the software development
 process.
 
 
-<a id="benefits"></a>
 
-### Agile and Flexible
+### <a id="benefits"></a> Agile and Flexible
 
 Brooklyn is a product built from the ground up for application agility. This
 includes portability across non-cloud, cloud, and PaaS targets; devops-style


Mime
View raw message