updated docs to use archetype
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/c75cadba Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/c75cadba Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/c75cadba Branch: refs/heads/0.6.0 Commit: c75cadbac3037bb29da874caf234f1033a1a318d Parents: 84cb713 Author: Alex Heneveld <[email protected]> Authored: Wed Sep 25 23:23:56 2013 +0100 Committer: Alex Heneveld <[email protected]> Committed: Wed Sep 25 23:23:56 2013 +0100 ---------------------------------------------------------------------- docs/dev/build/eclipse.include.md | 15 ++++--- docs/dev/build/ide.md | 76 ++++++++++++++-------------------- docs/dev/code/index.include.md | 23 +++++++++- docs/start/walkthrough/index.md | 63 +++++++++++++++++++--------- 4 files changed, 106 insertions(+), 71 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c75cadba/docs/dev/build/eclipse.include.md ---------------------------------------------------------------------- diff --git a/docs/dev/build/eclipse.include.md b/docs/dev/build/eclipse.include.md index 700f975..298d948 100644 --- a/docs/dev/build/eclipse.include.md +++ b/docs/dev/build/eclipse.include.md @@ -1,12 +1,15 @@ - Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases) - (typically availabile in the default Eclipse update site set) + (typically bundled with Eclipse or available in the default update site set) - Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates) - (typically availabile in the default Eclipse update site set) - -- Groovy Plugin: GRECLIPSE from [dist.springsource.org/release/GRECLIPSE/e4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2) - (or [for Eclipse 3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)) - You can even visit the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin) for more details. + (typically bundled with Eclipse or available in the default update site set) + +- Groovy Plugin: GRECLIPSE from + [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3) + (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2) + or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)). + Be sure to include Groovy 1.8.6 compiler support and Maven-Eclipse (m2e) support. + More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin). - TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c75cadba/docs/dev/build/ide.md ---------------------------------------------------------------------- diff --git a/docs/dev/build/ide.md b/docs/dev/build/ide.md index a51e71c..dabc400 100644 --- a/docs/dev/build/ide.md +++ b/docs/dev/build/ide.md @@ -11,57 +11,57 @@ git branch switches (sooo nice) can be slow, etc etc. But with a bit of a dance the IDE can still be your friend, making it much easier to run tests and debug. -Here are some general tips: - -* Add your favourite plugins for Maven, Groovy, Git and JavaScript, if necessary - -* Turn off auto-rebuild if it bothers you - -* Don't always trust the IDE to build correctly; if you hit a snag, - do a command-line ``mvn clean install`` (optionally with ``-DskipTests``) - then refresh the project (optionally regenerate dependencies). - Sometimes closing projects (so that it reads from your ``~/.m2/repository``) helps. +As a general tip, don't always trust the IDE to build correctly; if you hit a snag, +do a command-line ``mvn clean install`` (optionally with ``-DskipTests``) +then refresh the project. See instructions below for specific IDEs. - + ## Eclipse -If you're an Eclipse user, you'll probably want the Groovy, Maven (m2e), Git, JavaScript and TestNG plugins. -Via Help -> Install New Software, or from the Eclipse Marketplace, -we recommend: +If you're an Eclipse user, you'll probably want the Maven (m2e) plugin +and the Groovy Eclipse plugin (used for testing and examples primarily). +You may also want Git and TestNG plugins. +You can install these using Help -> Install New Software, or from the Eclipse Marketplace: {% readj eclipse.include.md %} -As of this writing, with Eclipse 4.2, m2e 1.1, and GrEclipse 2.7, -the codebase has been imported (Import -> Existing Maven Projects) -and successfully run with no errors. -However this isn't always the case. +As of this writing, Eclipse 4.2 and Eclipse 4.3 are commonly used, +and the codebase can be imported (Import -> Existing Maven Projects) +and successfully built and run inside an IDE. +However there are quicks, and mileage may vary. If you encounter issues, the following hints may be helpful: -* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later". - The build-helper connector is useful if you're prompted for it, but - do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway). - You can manually mark as permanently ignored certain errors; - this updates the pom.xml (and should be current). - -* m2e likes to put ``excluding="**"`` on `resources`` directories; if you're seeing funny missing files +* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh + can be useful to re-populate files which need to be copied to `target/` + +* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install - from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix ``.classpath``s). + from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix + `.classpath`s). Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure) or the filesystem, or use - the following command to remove these rogue blocks in the generated .classpath files: + the following command to remove these rogue blocks in the generated `.classpath` files: - ``find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \;`` +{% highlight bash %} +% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \; +{% endhighlight %} -* Getting the web console project to build nicely can be trickier. +* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later". + The build-helper connector is useful if you're prompted for it, but + do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway). + You can manually mark as permanently ignored certain errors; + this updates the pom.xml (and should be current). * You may need to ensure ``src/main/{java,resources}`` is created in each project dir, if (older versions) complain about missing directories, and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists): - ``find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \;`` +{% highlight bash %} +find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \; +{% endhighlight %} * You may need to add the groovy nature (or even java nature) to projects; with some maven-eclipse plugins this works fine, @@ -70,19 +70,6 @@ If you encounter issues, the following hints may be helpful: or edit the ``.project`` manually adding it to the project properties). The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful. - <!-- - FIXME Relates to old Grails, rather than new JavaScript web-console. - Should we just delete this section, or does any of it apply to the new web-console? - -* Getting the web console project to build nicely can be trickier. - If you're lucky it will just work... - But you may find you have to first build from the command-line, - then add all the source folders, and ``target/plugin-classes`` as a class file folder. - Easier may be just to run "grails run-app" in the directory to launch it (plus that does dynamic restarts), - and use the IDE as just a text editor (or use a different text editor for that project only). - Note too that some jiggery-pokery may currently be needed to get Groovy 1.8 playing nicely with Grails 1.3. - --> - If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.url}}/meta/contact.html) and we can hopefully share our pearls. (And if you have a tip we haven't mentioned please let us know that too!) @@ -90,7 +77,8 @@ If the pain starts to be too much, come find us on IRC #brooklyncentral or [else ## Intelli-J IDEA -Tips from Intelli-J users wanted! +Many of our contributers prefer Intelli-J. However none of them have yet volunteered any set-up tips. +[Be the first!]({{site.url}}/dev/tips/update-docs.html) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c75cadba/docs/dev/code/index.include.md ---------------------------------------------------------------------- diff --git a/docs/dev/code/index.include.md b/docs/dev/code/index.include.md index 62302f8..5655a40 100644 --- a/docs/dev/code/index.include.md +++ b/docs/dev/code/index.include.md @@ -4,11 +4,30 @@ Brooklyn is available at [GitHub brooklyncentral/brooklyn](http://github.com/bro {% highlight bash %} git clone [email protected]:brooklyncentral/brooklyn.git +cd brooklyn {% endhighlight %} -You'll find versions in branches, and examples in the **examples** sub-dir. -These examples are pushed to the [brooklyn-examples](http://github.com/brooklyncentral/brooklyn-examples) GitHub project when a version is released. +Build it with: +{% highlight bash %} +mvn clean install +{% endhighlight %} + +And launch it with: + +{% highlight bash %} +cd usage/dist/target/brooklyn-dist/ +bin/brooklyn launch +{% endhighlight %} + +Plenty of examples are in the **examples** sub-dir, +described [here]({{site.url}}/use/examples), +and pushed to the [brooklyn-examples](http://github.com/brooklyncentral/brooklyn-examples) +GitHub project when a version is released. + +Information on using Brooklyn -- configuring locations (in `brooklyn.properties`) +and adding new projects to a catalog -- can be found in the [User's Guide]({{site.url}}/use/guide/quickstart/index.html). +This document is intended to help people become familiar with the codebase. ## Project Structure http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c75cadba/docs/start/walkthrough/index.md ---------------------------------------------------------------------- diff --git a/docs/start/walkthrough/index.md b/docs/start/walkthrough/index.md index 6623cb9..3b4d819 100644 --- a/docs/start/walkthrough/index.md +++ b/docs/start/walkthrough/index.md @@ -3,6 +3,7 @@ layout: page title: Walkthrough toc: /toc.json --- +{% include fields.md %} ## Intro @@ -15,11 +16,30 @@ composed of: * a cluster of JBoss appservers * a MySQL database -Here's the essential code which creates these and sets them up -for management: +A sample project can be created using the Brooklyn maven quickstart archetype: + +{% highlight bash %} +export BROOKLYN_VERSION=0.6.0-SNAPSHOT +mvn archetype:generate \ + -DarchetypeGroupId=io.brooklyn -DarchetypeArtifactId=brooklyn-archetype-quickstart -DarchetypeVersion=${BROOKLYN_VERSION} \ + -DgroupId=com.acme.sample -DartifactId=brooklyn-sample -Dversion=0.1.0-SNAPSHOT -Dpackage=com.acme.sample.brooklyn +cd brooklyn-sample +{% endhighlight %} + +{% if SNAPSHOT %} +For a snapshot version, you must either have a local `mvn install` of Brooklyn as described +[here]({{site.url}}/dev/code/index.html) or include the following additional `-D` define in +in the `mvn archetype:generate` command: + +{% highlight bash %} + -DarchetypeCatalog=https://oss.sonatype.org/content/repositories/snapshots/archetype-catalog.xml +{% endhighlight %} +{% endif %} + +An application blueprint can then be defined as a class as follows: {% highlight java %} -public class WebClusterDatabaseExample extends AbstractApplication { +public class ClusterWebServerDatabaseSample extends AbstractApplication { @Override public void init() { MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)); @@ -29,18 +49,22 @@ public class WebClusterDatabaseExample extends AbstractApplication { {% endhighlight %} -## Runtime: the Web Console +## Runtime -Build and run this Brooklyn "Application", specifying a target location, and our application is deployed. +To launch this application, simply build the project and run the `start.sh` script +in the resulting assembly: {% highlight bash %} -export BROOKLYN_CLASSPATH=/path/to/your/project/target/classes -brooklyn launch --app brooklyn.demo.WebClusterDatabaseExample --location jclouds:aws-ec2:eu-west-1 +mvn clean assembly:assembly +cd target/brooklyn-sample-0.1.0-SNAPSHOT-dist/brooklyn-sample-0.1.0-SNAPSHOT/ +./start.sh application --class com.acme.sample.brooklyn.ClusterWebServerDatabaseSample \ + --location jclouds:aws-ec2:eu-west-1 {% endhighlight %} -Amazon is used in these screenshots, but lots of targets are supported (using [jclouds](http://jclouds.org)) -including fixed IP addresses and private clouds, -or just localhost (very handy for dev/test, and with port conflicts resolved automatically!). +Amazon is used in these screenshots, but lots of targets are supported, +including `--location localhost`, fixed IP addresses, and +everything supported by [jclouds](http://jclouds.org), from OpenStack to Google Compute. +**It is necessary to set up credentials and/or access, as described [here]({{ site.url }}/use/guide/defining-applications/common-usage#locations).** [](walkthrough-webconsole-map.png) @@ -53,7 +77,7 @@ and exposes operations ("effectors") that can be performed on entities. [](walkthrough-webconsole-details.png) -## Some Configuration and Management +## Topology, Dependencies, and Management Policies Of course in the real world, application deployments are more interesting; they do things and need configuration. For instance you might need to: @@ -76,7 +100,7 @@ block "at the last moment" when the value is needed (but after e.g. the VMs have been provisioned, to speed things up). {% highlight java %} -public class WebClusterDatabaseExample extends AbstractApplication { +public class ClusterWebServerDatabaseSample extends AbstractApplication { @Override public void init() { MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class) @@ -86,7 +110,7 @@ public class WebClusterDatabaseExample extends AbstractApplication { .configure("memberSpec", EntitySpec.create(JBoss7Server.class) .configure("httpPort", "8080+") .configure("war", WAR_PATH) - .configure(javaSysProp("brooklyn.example.db.url"), + .configure(JavaEntityMethods.javaSysProp("brooklyn.example.db.url"), formatString("jdbc:%s%s?user=%s\\&password=%s", attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD)))); } @@ -125,15 +149,16 @@ A separate policy operates at the ``Controlled`` cluster to ensure the load-balancer is updated as the pool of web servers expands and contracts. Fire up a JMeter session and blast the Nginx address. -The resizer policy scales up our cluster: +The auto-scaler policy scales up our cluster: -[](walkthrough-webconsole-scaling.png) +[](walkthrough-webconsole-scaling.png) -## Run it Yourself +## What Next? -All the code for this walkthrough (and even the JMeter script) is included with -Brooklyn as the ``simple-web-cluster`` example, +In addition to the sample project created by the archetype, with its README and +`assembly` build, you can find additional code related to this example +(and even the JMeter script) included with Brooklyn as the ``simple-web-cluster`` example, described [in detail here]({{site.url}}/use/examples/webcluster). For your applications, you might want to mix in other data stores, messaging systems, or on-line services including PaaS. @@ -184,4 +209,4 @@ If you want to adventure beyond ``localhost`` (the default), simply supply the your favourite cloud (e.g. ``aws-ec2:eu-west-1``) with credentials set up as described [here]({{ site.url }}/use/guide/management/index.html#startup-config). ---> \ No newline at end of file +-->
