http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/BUILDING.md ---------------------------------------------------------------------- diff --git a/console/app/site/BUILDING.md b/console/app/site/BUILDING.md new file mode 100644 index 0000000..7147b62 --- /dev/null +++ b/console/app/site/BUILDING.md @@ -0,0 +1,241 @@ +We love [contributions](http://hawt.io/contributing/index.html)! You may also want to know [how to hack on the hawtio code](http://hawt.io/developers/index.html) + +[hawtio](http://hawt.io/) can now be built **without** having to install node.js or anything first thanks to the [frontend-maven-plugin](https://github.com/eirslett/frontend-maven-plugin). This +will install node.js & npm into a subdirectory, run `npm install` to install dependencies & run the build like normal. + +## Building + +After you've cloned hawtio's git repo the first thing you should do is build the whole project. First ```cd``` into the root directory of the hawtio project and run: + + mvn clean install + +This will ensure all dependencies within the hawtio repo are built and any dependencies are downloaded and in your local repo. + +To run the sample web application for development, type: + + cd hawtio-web + mvn compile + mvn test-compile exec:java + +On OS X and linux the _mvn compile_ command above is unnecessary but folks have found on windows there can be timing issues with grunt and maven that make this extra step a requirement (see [issue #203 for more details](https://github.com/hawtio/hawtio/issues/203#issuecomment-15808516)) + +Or if you want to just run an empty hawtio and connect in hawtio to a remote container (e.g. connect to a Fuse Fabric or something via the Connect tab) just run + + cd hawtio-web + mvn clean jetty:run + +### How to resolve building error of hawtio-web + +In case you get any building error of `hawtio-web`, then it may be due permission error of your local `.npm` directory. This has been known to happen for osx users. To remedy this + + cd ~ + cd .npm + sudo chown -R yourusernamehere * + +Where `yourusernamehere` is your username. This will change the file permissions of the node files so you can build the project. After this try building the hawtio source code again. + + +### Trying Different Containers + +The above uses Jetty but you can try running hawtio in different containers via any of the following commands. Each of them runs the hawtio-web in a different container (with an empty JVM so no beans or camel by default). + + mvn tomcat7:run + mvn tomcat6:run + mvn jboss-as:run + mvn jetty:run + +## Incrementally compiling TypeScript + +For a more rapid development workflow its good to use incremental compiling of TypeScript and to use LiveReload (or LiveEdit) below too. + +So in a **separate shell** (while keeping the above shell running!) run the following commands: + + cd hawtio-web + mvn compile -Pwatch + +This will incrementally watch all the *.ts files in the src/main/webapp/app directory and recompile them into src/main/webapp/app/app.js whenever there's a change. + +## Incrementally compiling TypeScript inside IntelliJ (IDEA) + +The easiest way we've figured out how to use [IDEA](http://www.jetbrains.com/idea/) and TypeScript together is to setup an External Tool to run watchTsc; then you get (relatively) fast recompile of all the TypeScript files to a single app.js file; so you can just keep hacking code in IDEA and letting LiveReload reload your web page. + +* open the **Preferences** dialog +* select **External Tools** +* add a new one called **watchTsc** +* select path to **mvn** as the program and **compile -Pwatch** as the program arguments +* select **hawtio-web** as the working directory +* click on Output Filters... +* add a new Output Filter +* use this regular expression + +``` +$FILE_PATH$\($LINE$,$COLUMN$\)\: +``` + +Now when you do **Tools** -> **watchTsc** you should get a output in the Run tab. If you get a compile error when TypeScript gets recompiled you should get a nice link to the line and column of the error. + +**Note** when you do this you probably want the Run window to just show the latest compile errors (which is usually the last couple of lines). + +I spotted a handy tip on [this issue](http://youtrack.jetbrains.com/issue/IDEA-74931), if you move the cursor to the end of the Run window after some compiler output has been generated - pressing keys _META_ + _end_ (which on OS X is the _fn_ and the _option/splat_ and right cursor keys) then IDEA keeps scrolling to the end of the output automatically; you don't have to then keep pressing the "Scroll to end" button ;) + +## Adding additional Javascript dependencies + +Hawtio is (finally) adopting [bower](http://bower.io/) for managing dependencies, these are automatically pulled in when building the project. It's now really easy to add third-party Javascript/CSS stuff to hawtio: + +* cd into 'hawtio-web', and build it +* source 'setenv.sh' to add bower to your PATH (it's under node_modules) if you haven't installed it globally +* run 'bower install --save some-awesome-tool' +* run 'grunt bower wiredep' to update index.html +* commit the change to bower.json and index.html + +When running in development mode be sure you've run 'grunt bower' if you see 404 errors for the bower package you've installed. This is normally done for you when running 'mvn clean install' + +## Using LiveReload + +The LiveReload support allows you to edit the code and for the browser to automatically reload once things are compiled. This makes for a much more fun and RAD development environment!! + +The easiest method to run with LiveReload support is to cd into the "hawtio-web" module and run the following: + +mvn test-compile exec:java + +The sample server runs an embedded LiveReload server that's all set up to look at src/main/webapp for file changes. If you don't want to load all of the sample apps because you're connecting to another JVM you don't have to: + +mvn test-compile exec:java -DloadApps=false + + +The Live Reload server implementation is provided by [livereload-jvm](https://github.com/davidB/livereload-jvm). When using other methods run run hawtio like "mvn jetty:run" or "mvn tomcat:run" you can run [livereload-jvm](https://github.com/davidB/livereload-jvm) directly, for example from the hawtio-web directory: + + java -jar livereload-jvm-0.2.0-SNAPSHOT-onejar.jar -d src/main/webapp/ -e .*\.ts$ + +Install the [LiveReload](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) plugin for Chrome and then enable it for the website (click the live reload icon on the right of the address bar). There is also a LiveReload plugin for Firefox, you can get it straight from the [LiveReload site](http://livereload.com). + + +In another shell (as mentioned above in the "Incrementally compile TypeScript" section you probably want to auto-recompile all the TypeScript files into app.js in *another shell* via this command: + + cd hawtio-web + mvn compile -Pwatch + +Enable Live Reload in your browser (open [http://localhost:8282/hawtio/](http://localhost:8282/hawtio/) then click on the Live Reload icon to the right of the location bar). + +Now if you change any source (HTML, CSS, TypeScript, JS library) the browser will auto reload on the fly. No more context-switching between your IDE and your browser! :) + +To specify a different port to run on, just override the `jettyPort` property + + mvn test-compile exec:java -DjettyPort=8181 + +### Using your build & LiveReload inside other web containers + +TODO - this needs updating still... + +The easiest way to use other containers and still get the benefits of LiveReload is to create a symbolic link to the generated hawtio-web war in expanded form, in the deploy directory in your web server. + +e.g. to use Tomcat7 in LiveReload mode try the following to create a symbolic link in the tomcat/webapps directory to the **hawtio-web/target/hawtio-web-1.3-SNAPSHOT** directory: + + cd tomcat/webapps + ln -s ~/hawtio/hawtio-web/target/hawtio-web-1.3-SNAPSHOT hawtio + +Then use [livereload-jvm](https://github.com/davidB/livereload-jvm) manually as shown above. + +Now just run Tomcat as normal. You should have full LiveReload support and should not have to stop/start Tomcat or recreate the WAR etc! + +### Running hawtio against Kubernetes / OpenShift + +To try run a [local OpenShift V3 based on Kubernetes / Docker](http://fabric8.io/v2/getStarted.html) first + + opeshift start + +Then run the following: + + export KUBERNETES_MASTER=http://localhost:8080 + mvn test-compile exec:java + +You should now see the Kubernetes / OpenShift console at http://localhost:8282/ + +#### Using your build from inside Jetty + +For jetty you need to name the symlink directory **hawtio.war** for [Jetty to recognise it](http://www.eclipse.org/jetty/documentation/current/automatic-webapp-deployment.html). + + cd jetty-distribution/webapps + ln -s ~/hawtio/hawtio-web/target/hawtio-web-1.3-SNAPSHOT hawtio.war + +Another thing is for symlinks jetty uses the real directory name rather than the symlink name for the context path. + +So to open the application in Jetty open [http://localhost:8282/hawtio-web-1.3-SNAPSHOT/](http://localhost:8282/hawtio-web-1.3-SNAPSHOT/) + + +## Running Unit Tests + +You can run the unit tests via maven: + + cd hawtio-web + mvn test + +If you are using the [LiveReload plugin for Chrome](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) you can then hit the LiveReload icon to the right of the address bar and if you are running the watch profile, the tests are re-run every time there is a compile: + + mvn test -Pwatch + +Now the unit tests are all re-run whenever you edit the source. + +## Running integration Tests + +You can run the Protractor integration tests via maven: + + cd hawtio-web + mvn verify -Pitests + +This will run the tests headlessly, in [Phantomjs](http://phantomjs.org/). + +If you want to see the tests running, you can run them in Chrome with: + + cd hawtio-web + mvn verify -Pitests,chrome + +## How to Get Started Hacking the Code + +Check out the [hawtio technologies, tools and code walkthroughs](http://hawt.io/developers/index.html) + +## Trying hawtio with Fuse Fabric + +As of writing hawtio depends on the latest snapshot of [Fuse Fabric](http://fuse.fusesource.org/fabric/). To try out hawtio with it try these steps: + + 1. Grab the latest [Fuse Fabric source code](http://fuse.fusesource.org/source.html) and do a build in the fabric directory... + + git clone git://github.com/fusesource/fuse.git + cd fuse + cd fabric + mvn -Dtest=false -DfailIfNoTests=false clean install + + 2. Now create a Fuse Fabric instance + + cd fuse-fabric\target + tar xf fuse-fabric-99-master-SNAPSHOT.tar.gz + cd fuse-fabric-99-master-SNAPSHOT + bin/fusefabric + + 3. When the Fabric starts up run the command + + fabric:create + + to properly test things out you might want to create a new version and maybe some child containers. + +### Running hawtio with Fuse Fabric in development mode + + cd hawtio-web + mvn test-compile exec:java -Psnapshot,fabric + +### Running hawtio using `jetty-maven-plugin` with authentication enabled + +Running hawtio using `mvn jetty:run` will switch hawtio configuration to use system (instead of JNDI) properties. The default configuration uses +`<systemProperties>/<systemProperty>` list inside `jetty-maven-plugin` configuration. + +One of those properties is standard JAAS property `java.security.auth.login.config` pointing at Jetty-Plus JAAS LoginModule which uses `src/test/resources/users.properties` file for mapping +users to password and roles. + +By default this mapping is: + + admin=admin,admin,viewer + +However `hawtio.authenticationEnabled` is disabled (`false`) by default. So in order to run hawtio using Jetty Maven plugin with authentication enabled, you can either +change this property in `hawtio-web/pom.xml`, or simply run: + + mvn jetty:run -Dhawtio.authenticationEnabled=true \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/CHANGES.md ---------------------------------------------------------------------- diff --git a/console/app/site/CHANGES.md b/console/app/site/CHANGES.md new file mode 100644 index 0000000..17f30b1 --- /dev/null +++ b/console/app/site/CHANGES.md @@ -0,0 +1,262 @@ + +### Change Log + +#### 1.4.45 + +* Camel plugin supports new inflight exchanges from Camel 2.15 onwards +* Fixed Camel plugin to show convertBodyTo in the route diagram + +#### 1.4.38 ... 1.4.44 + +* Camel tracer and debugger now shows message bodies that are stream/file based +* Camel message browser now shows the java types of the headers and body +* Various improvements for fabric8 v2 +* Various bug fixes + +#### 1.4.37 + +* Ported the [API console to work on Kubernetes](https://github.com/hawtio/hawtio/issues/1743) so that the APIs tab appears on the Kubernetes console if you run hawtio inside Kubernetes and are running the [API Registry service](https://github.com/fabric8io/quickstarts/tree/master/apps/api-registry) +* Adds [Service wiring for Kubernetes](https://github.com/hawtio/hawtio/blob/master/docs/Services.md) so that its easy to dynamically link nav bars, buttons and menus to remote services running inside Kubernetes (e.g. to link nicely to Kibana, Grafana etc). +* Various [bug fixes](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.37+is%3Aclosed) + + +#### 1.4.36 ... 1.4.32 + +* Bug fixes +* Allow to configure `TomcatAuthenticationContainerDiscovery` classes to control how hawtio authenticates on Apache Tomcat +* Excluded some not needed JARs as dependencies +* Various improvements and fixes needed for fabric8 v2 + +#### 1.4.31 + +* Added hawtio-custom-app module to create a version of the hawtio-default war with a subset of the javascript code normally included in hawtio. +* Fixes [these 6 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.31+is%3Aclosed) + +#### 1.4.30 + +* Bug fixes +* Fixed Camel diagram to render in Firefox browser +* Hawtio Karaf Terminal now installs and works in Karaf 2.x and 3.0.x out of the box +* Upgraded to TypeScript 1.1.0 +* Fixed jolokia connectivity to Java containers with jolokia when running Kubernetes on RHEL / Fedora / Vagrant +* Fixes [these 14 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.30+is%3Aclosed) + +#### 1.4.29 + +* Bug fixes + +#### 1.4.28 + +* Bug fixes + +#### 1.4.27 + +* Reworked proxy +* Minor fixes to git file manipulation & RBAC + +#### 1.4.26 + +* You can now drag and drop files onto the wiki file listing; or from a file listing to your desktop/folders. +* Fixes [these 2 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.26) + +#### 1.4.25 + +* Lots of improvements for using hawtio as a great console for working with [fabric8 V2](http://fabric8.io/v2/index.html), [kubernetes](http://kubernetes.io/) and [OpenShift](https://github.com/openshift/origin) +* Fixes [these 8 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.25+is%3Aclosed) + +#### 1.4.24 + +* A new kuberetes plugin which now links to the hawtio console for any JVM which exposes the jolokia port (8778) +* Fixes session filter issue + +#### 1.4.23 + +* Bug fixes +* Fixes [these 31 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.23) + +#### 1.4.22 + +* Bug fixes +* Fixed hawtio connector to work with local and remote connections again +* Fixes [these 17 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.22) + +#### 1.4.21 + +* Bug fixes +* Optimized application initial load time, and added source mappings so view source works in browsers to aid javascript debugging +* Added support for [kubernetes](http://fabric8.io/gitbook/kubernetes.html) with fabric8 +* Hawtio terminal now also supports Karaf 2.4.x / 3.x (though requires some customization to enable hawtio-plgiin in Karaf ACL) +* Fixes [these 7 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.21) + +#### 1.4.20 + +* Bug fixes +* The source code can now be [built](http://hawt.io/building/index.html) without installing npm, just use plain Apache Maven. +* Hawtio terminal now also supports Karaf 3.x +* Fixed an issue deploying hawtio-war into WebLogic +* Fixes [these 10 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.20) + +#### 1.4.19 + +* Bug fixes +* Fixed so hawtio deploys out-of-the-box in Apache Tomcat and Apache ServiceMix 5.1 +* Fixes [these 46 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.19) + +#### 1.4.18 + +* Hawtio requires Java 1.7 onwards +* Authentication now detects if running on WebSphere, and adapts authentication to WebSphere specific credentials and APIs +* Filter now allow to filter by multi values separated by comma +* Camel sub tab for route metrics when using the new camel-metrics component +* Bug fixes + +#### 1.4.17 + +* Bug fixes + +#### 1.4.16 + +* Bug fixes + +#### 1.4.14 + +* Upgrades to jaxb, jackson, dozer and spring to play nicer with the latest [fabric8](http://fabric8.io/) distro +* Fixes [these 5 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.14+is%3Aclosed) + +#### 1.4.12 + +* [fabric8](http://fabric8.io/) plugin has an improved Containers page and the start of a nice deploy UI with draggy droppy +* Fixes [these 10 issues and enhancements](https://github.com/hawtio/hawtio/issues?q=milestone%3A1.4.12+is%3Aclosed) + +#### 1.4.11 + +* [fabric8](http://fabric8.io/) plugin has a nice funky 'App Store' style Profiles tab for selecting profiles +* ActiveMQ plugin can now edit and resend messages +* Minimised the generated JS to reduce the size +* Fixes [these 14 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=15&state=closed) +* Support for Java 1.6 is deprecated + +#### 1.4.4 + +* The Chrome Extension build worked, so we've a shiny new Chrome Extension! +* Various fixes for the new [fabric8](http://fabric8.io/) release +* Fixes [these 14 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=14&state=closed) + +#### 1.4.2 + +* New pane used for JMX/Camel/ActiveMQ tabs that allows resizing or hiding the JMX tree +* New terminal theme +* Restyled container list page in Fabric8 runtime view +* Switch from ng-grid to hawtio-simple-table for JMX attributes view +* Fixes [these 84 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=13&state=closed) + +#### 1.4.1 + +* Using new hawtio logo +* Quick bugfix release + +#### 1.4.0 + +* Theme support with two available themes, Default and Dark +* Better pluggable branding support +* Refactored preferences page into a slide out preferences panel, made preference tabs pluggable +* Relocated perspective switcher and incorporated it into the main navigation bar +* Perspective switcher now also maintains a list of 5 recently used connections automatically +* Added [fabric8](http://fabric8.io/) branding plugin +* Fixed some minor bugs and issues in the fabric plugin. +* Upgraded to [Jolokia](http://jolokia.org/) 1.2.1 +* Fixes [these 18 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=11&state=closed) + +#### 1.3.1 + +* Quick bugfix release +* Fixes [these 13 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=5&page=1&state=closed) + +#### 1.3.0 + +* [Hawtio Directives](http://hawt.io/directives/index.html) is now released as a separate JS file so its easy to consume in other angularjs based projects. +* Separate [IRC plugin example](https://github.com/hawtio/hawtio/tree/master/hawtio-plugin-examples/irc-client-plugin) to show how to develop external plugins for hawtio +* Upgraded to [Jolokia](http://jolokia.org/) 1.2 so that hawtio can discover other Jolokia processes via multicast +* ActiveMQ plugin now defaults to [showing all the real time attributes for queues](https://github.com/hawtio/hawtio/issues/1175) to avoid folks having to find the Queues folder. +* Updated to support the new package name of [fabric8 mbeans](http://fabric8.io/) +* Fixes [these 51 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=10&state=closed) + +#### 1.2.3 + +* New [hawtio Chrome Extension](http://hawt.io/getstarted/index.html) for easier connection to remote JVMs from your browser without having to run a hawtio server or connect through a web proxy +* Upgraded to TypeScript 0.9.5 which is faster +* [threads](https://github.com/hawtio/hawtio/tree/master/hawtio-web/src/main/webapp/app/threads) plugin to monitor JVM thread usage and status. +* Moved java code from hawtio-web into hawtio-system +* Clicking a line in the log plugin now shows a detail dialog with much more details. +* ActiveMQ plugin can now browse byte messages. +* Improved look and feel in the Camel route diagram. +* Breadcrumb navigation in Camel plugin to make it easier and faster to switch between CamelContext and routes in the selected view. +* Added Type Converter sub tab (requires Camel 2.13 onwards). +* Better support for older Internet Explorer browsers. +* Lots of polishing to work much better as the console for [fabric8](http://fabric8.io/) +* Fixes [these 175 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=9&state=closed) + +#### 1.2.2 + +* Added welcome page to aid first time users, and being able to easily dismiss the welcome page on startup. +* Added preference to configure the order/enabling of the plugins in the navigation bar, and to select a plugin as the default on startup. +* Added support for Apache Tomcat security using the conf/tomcat-users.xml file as user database. +* Added [quartz](http://hawt.io/plugins/quartz/) plugin to manage quartz schedulers. +* Allow to configure the HTTP session timeout used by hawtio. hawtio now uses the default timeout of the web container, instead of hardcoded value of 900 seconds. +* The [JMX](http://hawt.io/plugins/jmx/) plugin can now edit JMX attributes. +* the [osgi](http://hawt.io/plugins/osgi/) plugin now supports OSGi Config Admin and uses OSGi MetaType metadata for generating nicer forms (if the io.fabric8/fabric-core bundle is deployed which implements an MBean for introspecting the OSGi MetaType). +* Fixes [these 75 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=8&state=closed) + +#### 1.2.1 + +* New [Maven plugin](http://hawt.io/maven/) for running hawtio in your maven project; running Camel, Spring, Blueprint or tests. +* New plugins: + * [JUnit](http://hawt.io/plugins/junit/) for viewing/running test cases + * [API](http://hawt.io/plugins/api/) for viewing APIs from [Apache CXF](http://cxf.apache.org/) endpoints; currently only usable in a Fuse Fabric + * [IDE](http://hawt.io/plugins/ide/) for generating links to open files in your IDE; currently IDEA the only one supported so far ;) + * Site plugin for using hawtio to view and host your project website +* Improved the camel editor with a new properties panel on the right +* Fixes [these 51 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=3&state=closed) + +#### 1.2.0 + +* Connectivity + * New _JVMs_ tab lets you connect to remote JVMs on your local machine; which if a JVM does not have jolokia installed it will install it on the fly. (Requires tools.jar in the classpath) + * New _Connect_ tab to connect to a remote JVM running jolokia (and its now been removed from the Preferences page) +* ActiveMQ gets huge improvements in its tooling + * we can more easily page through messages on a queue + * move messages from one queue to another + * delete messages + * retry messages on a DLQ (in 5.9.x of ActiveMQ onwards) + * purge queues +* Camel + * Neater message tracing; letting you zoom into a message and step through the messages with video player controls + * Can now forward messages on any browseable camel enpdoint to any other Camel endpoints +* Fabric + * Redesigned fabric view allows quick access to versions, profiles and containers, mass-assignment/removal of profiles to containers + * Easier management of features deployed in a profile via the "Edit Features" button. + * Several properties now editable on container detail view such as local/public IP and hostname +* General + * Secured embedded jolokia, performs authentication/authorization via JAAS + * New login page + * Redesigned help pages +* Tons more stuff we probably forgot to list here but is mentioned in [the issues](https://github.com/hawtio/hawtio/issues?milestone=4&state=closed) :) +* Fixes [these 407 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=4&state=closed) + +#### 1.1 + +* Added the following new plugins: + * [forms](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/forms/doc/developer.md) a developer plugin for automatically creating tables and forms from json-schema models + * [infinispan](http://hawt.io/plugins/infinispan/) for viewing metrics for your Infinispan caches or using the CLI to query or update them + * [jclouds](http://hawt.io/plugins/jclouds/) to help make your cloud hawt + * [maven](http://hawt.io/plugins/maven/) to let you search maven repositories, find versions, view source or javadoc + * [tree](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/tree/doc/developer.md) a developer plugin to make it easier to work with trees +* Added a new real time Camel profile view and the first version of a web based wiki based camel editor along with improvements to the diagram rendering +* Added more flexible documentation system so that plugins are now self documenting for users and developers +* Fixes [these 80 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=2&state=closed) + +#### 1.0 + +* First main release of hawtio with [lots of hawt plugins](http://hawt.io/plugins/index.html). +* Fixes [these 74 issues and enhancements](https://github.com/hawtio/hawtio/issues?milestone=1&state=closed) + http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/console/app/site/CONTRIBUTING.md b/console/app/site/CONTRIBUTING.md new file mode 100644 index 0000000..9da1268 --- /dev/null +++ b/console/app/site/CONTRIBUTING.md @@ -0,0 +1,62 @@ +We love contributions! We really need your help to make [hawtio](http://hawt.io/) even more hawt, so please [join our community](http://hawt.io/community/index.html)! + +Many thanks to all of our [existing contributors](https://github.com/hawtio/hawtio/graphs/contributors)! But we're greedy, we want more! hawtio is _hawt_, but it can be _hawter_! :). We have [lots of plugins](http://hawt.io/plugins/index.html) but they can be improved and we want more plugins! + +Here's some notes to help you get started: + +## Getting Started + +* Make sure you have a [GitHub account](https://github.com/signup/free) as you'll need it to submit issues, comments or pull requests. +* Got any ideas for how we can improve hawtio? Please [submit an issue](https://github.com/hawtio/hawtio/issues?state=open) with your thoughts. Constructive criticism is always greatly appreciated! +* Fancy submitting [any nice screenshots of how you're using hawtio?](https://github.com/hawtio/hawtio/tree/master/website/src/images/screenshots) A quick Youtube screencast would be even _hawter_ or a blog post/article we can link to? Just [submit an issue](https://github.com/hawtio/hawtio/issues?state=open) (or fork and patch the [website](https://github.com/hawtio/hawtio/tree/master/website/src/) or any Markdown docs in our repository directly) and we'll merge it into our website. +* Fancy submitting your cool new dashboard configuration or some wiki docs? See below on how to do that... +* Search [our issue tracker](https://github.com/hawtio/hawtio/issues?state=open) and see if there's been any ideas or issues reported for what you had in mind; if so please join the conversation in the comments. +* Submit any issues, feature requests or improvement ideas [our issue tracker](https://github.com/hawtio/hawtio/issues?state=open). + * Clearly describe the issue including steps to reproduce when it is a bug. + * Make sure you fill in the earliest version that you know has the issue. + +### Fancy hacking some code? + +* If you fancy working on some code, check out the these lists of issues: + * [open apprentice tasks](https://github.com/hawtio/hawtio/issues?labels=apprentice+tasks&page=1&sort=updated&state=open) - which are moderately easy to fix and tend to have links to which bits of the code to look at to fix it or + * [all open issues](https://github.com/hawtio/hawtio/issues?state=open) if you fancy being more adventurous. + * [hawt ideas](https://github.com/hawtio/hawtio/issues?labels=hawt+ideas&page=1&sort=updated&state=open) if you're feeling like a ninja and fancy tackling our harder issues that tend to add really _hawt_ new features! + +* To make code changes, fork the repository on GitHub then you can hack on the code. We love any contribution such as: + * fixing typos + * improving the documentation or embedded help + * writing new test cases or improve existing ones + * adding new features + * improving the layout / design / CSS + * creating a new [plugin](http://hawt.io/plugins/index.html) + +## Submitting changes to hawtio + +* Push your changes to your fork of the [hawtio repository](https://github.com/hawtio/hawtio). +* Submit a pull request to the repository in the **hawtio** organization. +* If your change references an existing [issue](https://github.com/hawtio/hawtio/issues?state=open) then use "fixes #123" in the commit message (using the correct issue number ;). + +## Submitting changes dashboard and wiki content + +Hawtio uses the [hawtio-config repository](https://github.com/hawtio/hawtio-config) to host its runtime configuration. When you startup hawtio by default it will clone this repository to the configuration directory (see the [configuration document](https://github.com/hawtio/hawtio/blob/master/docs/Configuration.md) or more detail). + +In development mode if you are running hawtio via the **hawtio-web** directory, then your local clone of the [hawtio-config repository](https://github.com/hawtio/hawtio-config) will be in the **hawtio/hawtio-web/hawtio-config directory**. If you've added some cool new dashboard or editted any files via the hawtio user interface then your changes will be committed locally in this directory. + +If you are a committer and want to submit any changes back just type: + + cd hawtio-config + git push + +Otherwise if you want to submit pull requests for your new dashboard or wiki content then fork the [hawtio-config repository](https://github.com/hawtio/hawtio-config) then update your hawtio-config directory to point to this directory. e.g. edit the hawtio-config/.git/config file to point to your forked repository. + +Now perform a git push as above and then submit a pull request on your forked repo. + +# Additional Resources + +* [hawtio FAQ](http://hawt.io/faq/index.html) +* [General GitHub documentation](http://help.github.com/) +* [GitHub create pull request documentation](hhttps://help.github.com/articles/creating-a-pull-request) +* [Here is how to build the code](http://hawt.io/building/index.html) +* [More information for developers in terms of hawtio technologies, tools and code walkthroughs](http://hawt.io/developers/index.html) +* [join the hawtio community](http://hawt.io/community/index.html) + http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/DEVELOPERS.md ---------------------------------------------------------------------- diff --git a/console/app/site/DEVELOPERS.md b/console/app/site/DEVELOPERS.md new file mode 100644 index 0000000..73034a7 --- /dev/null +++ b/console/app/site/DEVELOPERS.md @@ -0,0 +1,184 @@ +We love [contributions](http://hawt.io/contributing/index.html). This page is intended to help you get started hacking on the code, it contains various information on technology and tools together with code walk-throughs. + +Welcome and enjoy! Its hawt, but stay cool! :) + +<div class="alert alert-info"> +Hawtio 2.x Overview! Ooh, shiny shiny... <a href="https://github.com/hawtio/hawtio/blob/master/docs/Overview2dotX.md";>look here!</a> +</div> + +## Building the code + +Check out <a class="btn btn-primary btn-large" href="http://hawt.io/building/index.html";>How To Build The Code</a> if you want to start hacking on the source. + +## Architecture + +**hawtio** is a single page application which is highly modular and capable of dynamically loading [plugins](http://hawt.io/plugins/index.html) based on the capability of the server. + +You may want to check out: + +* [Current hawtio plugins](http://hawt.io/plugins/index.html) +* [External AngularJS Directives](http://hawt.io/developers/directives.html) +* [How plugins work](http://hawt.io/plugins/howPluginsWork.html) + +## Developer Tools + +The following are recommended if you want to contribute to the code + +* [hawtio Typescript API documentation](http://hawt.io/ts-api/index.html) Typedoc output for all of the typescript code on hawtio's master branch +* [IntelliJ IDEA EAP 12 or later](http://confluence.jetbrains.net/display/IDEADEV/IDEA+12+EAP) as this has TypeScript support and is the daddy of IDEs! +* [There are other TypeScript plugins](http://blogs.msdn.com/b/interoperability/archive/2012/10/01/sublime-text-vi-emacs-typescript-enabled.aspx) if you prefer Sublime, Emacs or VIM. (Unfortunately we're not aware of an eclipse plugin yet). +* [AngularJS plugin for IDEA](http://plugins.jetbrains.com/plugin/?id=6971) if you use [IDEA](http://www.jetbrains.com/idea/) then this plugin really helps work with Angular JS +* [AngularJS plugin for Chrome](https://chrome.google.com/webstore/detail/angularjs-batarang/ighdmehidhipcmcojjgiloacoafjmpfk) which is handy for visualising scopes and performance testing etc. +* [JSONView plugin for Chrome](https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc) makes it easy to visualise JSON returned by the [REST API of Jolokia](http://jolokia.org/reference/html/protocol.html) +* [Apache Maven 3.0.3 or later](http://maven.apache.org/) +* [gruntjs](http://gruntjs.com/) a build tool for JavaScript. See nearly the beginning of this document for details of how to install and use. +* [Dash.app](http://kapeli.com/) is a handy tool for browsing API documentation for JavaScript, HTML, CSS, jquery, AngularJS etc. + +## JavaScript Libraries + +For those interested in [contributing](http://hawt.io/contributing/index.html) or just learning how to build single page applications, here is a list of the various open source libraries used to build hawtio: + +* [AngularJS](http://angularjs.org/) is the web framework for performing real time two-way binding of HTML to the model of the UI using simple declarative attributes in the HTML. +* [jolokia](http://jolokia.org/) is the server side / JVM plugin for exposing JMX as JSON over HTTP. It's awesome and is currently the only server side component of hawtio. +* [TypeScript](http://typescriptlang.org/) is the language used to implement the console; it compiles to JavaScript and adds classes, modules, type inference & type checking. We recommend [IntelliJ IDEA EAP 12 or later](http://confluence.jetbrains.net/display/IDEADEV/IDEA+12+EAP) for editing TypeScript--especially if you don't use Windows or Visual Studio (though there is a Sublime Text plugin too). +* [angular ui](http://angular-ui.github.com/) is a library of AngularJS additions and directives +* [d3](http://d3js.org/) is the visualization library used to do the force layout graphs (for example the diagram view for ActiveMQ) +* [cubism](http://square.github.com/cubism/) implements the real-time horizon charts +* [dagre](https://github.com/cpettitt/dagre) for graphviz style layouts of d3 diagrams (e.g. the Camel diagram view). +* [ng-grid](http://angular-ui.github.com/ng-grid/) an AngualrJS based table/grid component for sorting/filtering/resizing tables +* [marked](https://github.com/chjj/marked) for rendering Github-flavoured Markdown as HTML +* [DataTables](http://datatables.net/) for sorted/filtered tables (though we are migrating to ng-grid as its a bit more natural for AngularJS) +* [DynaTree](http://wwwendt.de/tech/dynatree/doc/dynatree-doc.html) for tree widget +* [jQuery](http://jquery.com/) small bits of general DOM stuff, usually when working with third-party libraries which don't use AngularJS +* [Twitter Bootstrap](http://twitter.github.com/bootstrap/) for CSS +* [Toastr](https://github.com/CodeSeven/toastr) for notifications + +We're not yet using it but these look handy too: + +* [jquery-mobile-angular-adapter](https://github.com/tigbro/jquery-mobile-angular-adapter) for easy interop of jQuery Mobile and AngularJS +* [breezejs](http://www.breezejs.com/) for easy LINQ / ActiveRecord style database access and synchronization + +## API documentation + +If you are interested in working on the code the following references and articles have been really useful so far: + +* [available AngularJS Directives](http://hawt.io/developers/directives.html) +* [angularjs API](http://docs.angularjs.org/api/) +* [bootstrap API](http://twitter.github.com/bootstrap/base-css.html) +* [cubism API](https://github.com/square/cubism/wiki/API-Reference) +* [d3 API](https://github.com/mbostock/d3/wiki/API-Reference) +* [ng-grid API](http://angular-ui.github.com/ng-grid/#/api) +* [datatables API](http://www.datatables.net/api) +* [javascript API](http://www.w3schools.com/jsref/default.asp) +* [sugarjs API](http://sugarjs.com/api/Array/sortBy) +* [icons from Font Awesome](http://fortawesome.github.com/Font-Awesome/) + +### Developer Articles, Forums and Resources + +* [Fun with AngularJS](http://devgirl.org/2013/03/21/fun-with-angularjs/) is great overview on AngularJS! +* [egghead.io various short angularjs videos](http://egghead.io/) +* [great angularjs talk](http://www.youtube.com/angularjs) +* [AngularJS plugins](http://ngmodules.org/) +* [AngularJS tips and tricks](http://deansofer.com/posts/view/14/AngularJs-Tips-and-Tricks-UPDATED) +* [more AngularJS magic to supercharge your webapp](http://www.yearofmoo.com/2012/10/more-angularjs-magic-to-supercharge-your-webapp.html#) +* [AngularJS questions on stackoverflow](http://stackoverflow.com/questions/tagged/angularjs) +* [Modeling Data and State in Your AngularJS Application](http://joelhooks.com/blog/2013/04/24/modeling-data-and-state-in-your-angularjs-application/) +* [6 Common Pitfalls Using Scopes](http://thenittygritty.co/angularjs-pitfalls-using-scopes) + +## Code Walkthrough + +If you fancy contributing--and [we love contributions!](http://hawt.io/contributing/index.html)--the following should give you an overview of how the code hangs together: + +* hawtio is a single page web application, from [this single page of HTML](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/index.html) +* We use [AngularJS routing](http://docs.angularjs.org/api/ng.directive:ngView) to display different [partial pages](https://github.com/hawtio/hawtio/tree/master/hawtio-web/src/main/webapp/app/core/html) depending on which tab/view you choose. You'll notice that the partials are simple HTML fragments which use [AngularJS](http://angularjs.org/) attributes (starting with **ng-**) along with some {{expressions}} in the markup. +* Other than the JavaScript libraries listed above which live in [webapp/lib](https://github.com/hawtio/hawtio/tree/master/hawtio-web/src/main/webapp/lib) and are [included in the index.html](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/index.html), we then implement [AngularJS](http://angularjs.org/) controllers using [TypeScript](http://typescriptlang.org/). All the typescript source is in the [in files in webapp/app/pluginName/js/ directory](https://github.com/hawtio/hawtio/tree/master/hawtio-web/src/main/webapp/app) which is then compiled into the [webapp/app/app.js file](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/app.js) +* To be able to compile with TypeScript's static type checking we use the various [TypeScript definition files](https://github.com/hawtio/hawtio/tree/master/hawtio-web/src/main/d.ts) to define the optional statically typed APIs for the various APIs we use +* The controllers use the [Jolokia JavaScript API](http://jolokia.org/reference/html/clients.html#client-javascript) to interact with the server side JMX MBeans + +### How the Tabs Work + +Tabs can dynamically become visible or disappear based on the following: + +* the contents of the JVM +* the [plugins](plugins.html), +* and the current UI selection(s). + +[Plugins](plugins.html) can register new top-level tabs by adding to the [topLevelTabs](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/log/js/logPlugin.ts#L9) on the workspace which can be dependency injected into your plugin via [AngularJS Dependency Injection](http://docs.angularjs.org/guide/di). + +The [isValid()](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/log/js/logPlugin.ts#L12) function is then used to specify when this top-level tab should be visible. + +You can register [subLevelTabs](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/log/js/logPlugin.ts#L16) which are then visible when the [right kind of MBean is selected](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/log/js/logPlugin.ts#L19). + +For more detail check out the [plugin documentation](plugins.html). + +#### Enable Source Maps for Easier Debugging + +We recommend you enable [Source Maps](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit?pli=1) in your browser (e.g. in Chrome) for easier debugging by clicking on the bottom-right Settings icon in the *JavaScript Console* and [enabling Source Maps support such as in this video](http://www.youtube.com/watch?v=-xJl22Kvgjg). + +#### Notes on Using IDEA + +To help IDEA navigate to functions in your source and to avoid noise, you may want to ignore some JavaScript files in IDEA so that they are not included in the navigation. Go to `Settings/Preferences -> File Types -> Ignore Files` then add these patterns to the end: + + *.min.js;*-min.js + +Ignoring these files will let IDEA ignore the minified versions of the JavaScript libraries. + +Then select the generated [webapp/app/app.js file](https://github.com/hawtio/hawtio/blob/master/hawtio-web/src/main/webapp/app/app.js) in the Project Explorer, right-click and select _Mark as Plain Text_ so that it is ignored as being JavaScript source. This hint came from [this forum thread](http://devnet.jetbrains.net/message/5472690#5472690), hopefully there will be a nicer way to do all this one day! + +#### Handy AngularJS debugging tip + +Open the JavaScript Console and select the _Console_ tab so you can type expressions into the shell. +Select part of the DOM of the scope you want to investigate +Right click and select _Inspect Element_ +In the console type the following + + s = angular.element($0).scope() + +You have now defined a variable called _s_ which contains all the values in the active AngularJS scope so you can navigate into the scope and inspect values or invoke functions in the REPL, etc. + +#### Handy JQuery debugging tip + +Open the JavaScript Console and select the _Console_ tab so you can type expressions into the shell. +Select a DOM element (e.g., button) for which you want to check what jquery event handlers are attached. +In the console type: + + jQuery._data($0, "events") + +You'll get array of events. When you expand the events and go to "handler" member (e.g., `click->0->handler`), you can: + +* in Firebug right click `function()` and select _Inspect in Script Panel_ +* in Chrome dev tools right click `function()` and select _Show Function Definition_ + +to see the body of handler method. + +### Handy AngularJS programming tips + +#### Use a nested scope object to own state for 2 way binding + +When binding models to HTML templates; its always a good idea to use a level of indirection between the $scope and the property. So rather than binding to $scope.name, bind to $scope.entity.name then have code like + + $scope.entity = { "name": "James" }; + +This means to that to reset the form you can just do + + $scope.entity = {}; + +And you can then refer to the entire entity via **$scope.entity**. Another reason for doing this is that when you have lots of nested scopes; for example when using nested directives, or using includes or layouts, you don't get inheritence issues; since you can acess $scope.entity from child scopes fine. + +#### When working with $routeParams use the $scope.$on + +Its often useful to use $routeParams to get the URI template parameters. However due to [the rules on who gets the $routeParams injected](http://deansofer.com/posts/view/14/AngularJs-Tips-and-Tricks-UPDATED#routing) when using layouts and so forth, the $routeParams can be empty. + +So put all code that uses $routeParams inside the $routeChangeSuccess callback: + + $scope.$on('$routeChangeSuccess', function(event, routeData){ + // process $routeParams now... + }); + +### Local Storage + +hawtio uses local storage to store preferences and preferred views for different kinds of MBean type and so forth. + +You can view the current Local Storage in the Chrome developer tools console in the Resources / Local Storage tab. + +If you ever want to clear it out in Chrome on OS X you'll find this located at `~/Library/Application Support/Google/Chrome/Default/Local Storage`. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/FAQ.md ---------------------------------------------------------------------- diff --git a/console/app/site/FAQ.md b/console/app/site/FAQ.md new file mode 100644 index 0000000..725b4f8 --- /dev/null +++ b/console/app/site/FAQ.md @@ -0,0 +1,215 @@ +### General Questions + +General questions on all things hawtio. + +#### What is the license? + +hawtio uses the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.txt). + +#### What does hawtio do? + +It's a [pluggable](http://hawt.io/plugins/index.html) management console for Java stuff which supports any kind of JVM, any kind of container (Tomcat, Jetty, Karaf, JBoss, Fuse Fabric, etc), and any kind of Java technology and middleware. + +#### How do I install hawtio? + +See the [Getting Started Guide](http://hawt.io/getstarted/index.html) and the [Configuration Guide](http://hawt.io/configuration/index.html) + +#### How do I configure hawtio? + +Mostly hawtio just works. However, please check out the [Configuration Guide](http://hawt.io/configuration/index.html) to see what kinds of things you can configure via system properties, environment variables, web.xml context-params or dependency injection. + +#### How do I disable security? + +Since 1.2-M2 of hawtio we enable security by default using the underlying application container's security mechanism. + +Here's how to [disable security](https://github.com/hawtio/hawtio/blob/master/docs/Configuration.md#configuring-or-disabling-security-in-karaf-servicemix-fuse) if you wish to remove the need to login to hawtio. + +#### Which Java version is required? + +Hawtio 1.4 onwards requires Java 7 or 8. +Hawtio 1.3 or older supports Java 6 and 7. + +#### How do I enable hawtio inside my Java Application / Spring Boot / DropWizard / Micro Service + +The easiest thing to do is add jolokia as a java agent via a java agent command line: +``` +java -javaagent:jolokia-agent.jar=host=0.0.0.0 -jar foo.jar +``` + +Then by default you can connect on http;//localhost:8778/jolokia to access the jolokia REST API. + +Now you can use hawtio (e.g. the Google Chrome Extension or the stand alone hawtio application) to connect to it - and it then minimises the effect of hawtio/jolokia on your app (e.g. you don't need to mess about with whats inside your application or even change the classpath) + +#### How do I connect to my remote JVM? + +All that's required for hawtio to connect to any remote JVM is that a [jolokia agent](http://jolokia.org/agent.html) is attached to the JVM you wish to connect to. This can be done in various ways. + +Firstly if you are using [Fuse](http://www.jboss.org/products/fuse) or [Apache ActiveMQ 5.9.x or later](http://activemq.apache.org/) then you already have jolokia enabled by default. + +If a JVM has no jolokia agent, you can use the **Local** tab of the **Connect** menu (in 1.2.x or later of **hawtio-default.war**). The Local tab lists all local Java processes on the same machine (just like JConsole does). + +For JVMs not running a jolokia agent already, there's a start button (on the right) which will dynamically add the [jolokia JVM agent](http://jolokia.org/agent/jvm.html) into the selected JVM process. You can then click on the Agent URL link to connect into it. + +Note that the Local plugin only works when the JVM running hawtio has the **hawtio-local-jvm-mbean** plugin installed (which depends on the JVM finding the com.sun.tools.attach.VirtualMachine API that jconsole uses and is included in the hawtio-default.war). BTW if you don't see a **Local** tab inside the **Conect** menu in your hawtio application; check the log of your hawtio JVM; there might be a warning around com.sun.tools.attach.VirtualMachine not being available on the classpath. Or you could just try using the [exectuable jar](http://hawt.io/getstarted/index.html) to run hawtio which seems to work on most platforms. + +Note also that the **Local** tab only works when the process is on the same machine as the JVM running hawtio. So a safer option is just to make sure there's a jolokia agent running in each JVM you want to manage with hawtio. + +There are a [few different agents you can use](http://jolokia.org/agent.html): + +* [WAR agent](http://jolokia.org/agent/war.html) if you are using a servlet / EE container +* [OSGi agent](http://jolokia.org/agent/osgi.html) if you are using OSGi (note that Jolokia is enabled by default in [Fuse](http://www.jboss.org/products/fuse) so you don't have to worry) +* [JVM agent](http://jolokia.org/agent/jvm.html) if you are using a stand alone Java process + +So once you've got a jolokia agent in your JVM you can test it by accessing http://host:port/jolokia in a browser to see if you can view the JSON returned for the version information of the jolokia agent. + +Assuming you have jolokia working in your JVM, then you can use the **Remote** tab on the **Connect** menu in hawtio to connect; just enter the host, port, jolokia path and user/password. + +After trying the above if you have problems connecting to your JVM, please [let us know](http://hawt.io/community/index.html) by [raising an issue](https://github.com/hawtio/hawtio/issues?state=open) and we'll try to help. + +#### How do I install a plugin? + +Each hawtio distro has these [browser based plugins](http://hawt.io/plugins/index.html) inside already; plus hawtio can discover any other external plugins deployed in the same JVM too. + +Then the hawtio UI updates itself in real time based on what it can find in the server side JVM it connects to. So, for example, if you connect to an empty tomcat/jetty you'll just see things like JMX and tomcat/jetty (and maybe wiki / dashboard / maven if you're using hawtio-default.war which has a few more server side plugins inside). + +Then if you deploy a WAR which has ActiveMQ or Camel inside it, you should see an ActiveMQ or Camel tab appear as you deploy code which registers mbeans for ActiveMQ or Camel. + +So usually, if you are interested in a particular plugin and its not visible in the hawtio UI (after checking your preferences in case you disabled it), usually you just need to deploy or add a server side plugin; which is usually a case of deploying some Java code (e.g. ActiveMQ, Camel, Infinispan etc). + +#### What has changed lately? + +Try have a look at the [change log](http://hawt.io/changelog.html) to see the latest changes in hawtio! + +#### Where can I find more information? + +Try have a look at the [articles and demos](http://hawt.io/articles/index.html) to see what other folks are saying about hawtio. + +#### Why does hawtio log a bunch of 404s to the javascript console at startup? + +The hawtio help registry tries to automatically discover help data for each registered plugin even if plugins haven't specifically registered a help file. + +#### Why does hawtio have its own wiki? + +At first a git-based wiki might not seem terribly relevant to hawtio. A wiki can be useful to document running systems and link to the various consoles, operational tools and views. Though in addition to being used for documentation, hawtio's wiki also lets you view and edit any text file; such as Camel routes, Fuse Fabric profiles, Spring XML files, Drools rulebases, etc. + +From a hawtio perspective though its wiki pages can be HTML or Markdown and then be an AngularJS HTML partial. So it can include JavaScript widgets; or it can include [AngularJS directives](http://docs.angularjs.org/guide/directive). + +This lets us use HTML and Markdown files to define custom views using HTML directives (custom tags) from any [hawtio plugins](http://hawt.io/plugins/index.html). Hopefully over time we can build a large library of HTML directives that folks can use inside HTML or Markdown files to show attribute values or charts from MBeans in real time, to show a panel from a dashboard, etc. Then folks can make their own mashups and happy pages showing just the information they want. + +So another way to think of hawtio wiki pages is as a kind of plugin or a custom format of a dashboard page. Right now each dashboard page assumes a grid layout of rectangular widgets which you can add to and then move around. However with a wiki page you can choose to render whatever information & widgets you like in whatever layout you like. You have full control over the content and layout of the page! + +Here are some [sample](https://github.com/hawtio/hawtio/issues/103) [issues](https://github.com/hawtio/hawtio/issues/62) on this if you want to help! + +So whether the hawtio wiki is used for documentation, to link to various hawtio and external resources, to create custom mashups or happy pages or to provide new plugin views--all the content of the wiki is audited, versioned and stored in git so it's easy to see who changed what, when and to roll back changes, etc. + +#### How to I install hawtio as web console for Apache ActiveMQ + +You can use hawtio to remote manage any ActiveMQ brokers without the need to co-install hawtio together with the ActiveMQ broker. However you can also install hawtio with the broker if you want. Dejan Bosanac [blogged how to do this](http://sensatic.net/activemq/activemq-and-hawtio.html). + + +### Problems/General Questions about using hawtio + +Questions relating to errors you get while using hawtio or other general questions: + +#### How can I hide or move tabs to different perspectives? + +An easy way is to use a plugin to reconfigure the default perspective definition. Have a look at the [custom-perspective](https://github.com/hawtio/hawtio/tree/master/hawtio-plugin-examples/custom-perspective) for a plugin-based solution. + +From **hawtio 1.2.2** onwards you can reorder and hide plugins from the preference. + + +#### Provider sun.tools.attach.WindowsAttachProvider could not be instantiated: java.lang.UnsatisfiedLinkError: no attach in java.library.path + +If you see an error like this: +``` +java.util.ServiceConfigurationError: com.sun.tools.attach.spi.AttachProvider: Provider sun.tools.attach.WindowsAttachProvider could not be instantiated: java.lang.UnsatisfiedLinkError: no attach in java.library.path +``` +when starting up or trying the **Connect/Local** tab then its probably related to [this issue](http://stackoverflow.com/questions/14027164/fix-the-java-lang-unsatisfiedlinkerror-no-attach-in-java-library-path) as was found on [#718](https://github.com/hawtio/hawtio/issues/718#issuecomment-27677738). + +Basically you need to make sure that you have JAVA_HOME/bin on your path. e.g. try this first before starting hawtio: +``` +set path=%path%;%JAVA_HOME%\jre\bin +``` + +#### The Terminal plugin in Karaf does not work + +The terminal plugin may have trouble the first time in use, not being able to connect and show the terminal. Try selecting another plugin, and go back to the terminal plugin a bit later, and it then may be able to login. Also if the screen is all black, then pressing ENTER may help show the terminal. + + + + +### Plugin Questions + +Questions on using the available plugins: + +#### What plugins are available? + +See the list of [hawtio plugins](http://hawt.io/plugins/index.html) + +#### What is a plugin? + +See [How Plugins Work](http://hawt.io/plugins/howPluginsWork.html) + + +#### Why does the OSGi tab not appear on GlassFish? + +This is a [reported issue](https://github.com/hawtio/hawtio/issues/158). It turns out that the standard OSGi MBeans (in the osgi.core domain) are not installed by default on GlassFish. + +The workaround is to install the [Gemini Management bundle](http://www.eclipse.org/gemini/management/) then you should see the MBeans in the osgi.core domain in the JMX tree; then the OSGi tab should appear! + + +### Camel Questions + +Questions on using [Apache Camel](http://camel.apache.org/) and hawtio. + +#### The Camel plugin is not visible or does not show any Camels + +The Camel plugin currently requires that the Camel MBeans are stored using the default domain name which is `org.apache.camel`. So if you configure Camel to use a different name, using the `mbeanObjectDomainName` configuration, then the Camel plugin will not work. See details reported in ticket [1712](https://github.com/hawtio/hawtio/issues/1712). + +#### Why does the Debug or Trace tab not appear for my Camel route? + +The Debug and Trace tabs depend on the JMX MBeans provided by the Camel release you use. + +* the Debug tab requires at least version 2.12.x or later of your Camel library to be running +* the Trace tab requires either a 2.12.x or later distro of Camel or a Fuse distro of Camel from about 2.8 or later + + +### Developer Questions + +Questions on writing new plugins or hacking on existing ones: + +#### How do I build the project? + +If you just want to run hawtio in a JVM then please see the [Getting Started](http://hawt.io/getstarted/index.html) section. + +If you want to hack the source code then check out [how to build hawtio](http://hawt.io/building/index.html). + +#### What code conventions do you have? + +Check out the [Coding Conventions](https://github.com/hawtio/hawtio/blob/master/docs/CodingConventions.md) for our recommended approach. + +#### What can my new plugin do? + +Anything you like :). So long as it runs on a web browser, you're good to go. Please start [contributing](http://hawt.io/contributing/index.html)! + +#### Do I have to use TypeScript? + +You can write hawtio plugins in anything that runs in a browser and ideally compiles to JavaScript. So use pure JavaScript, CoffeeScript, EcmaScript6-transpiler, TypeScript, GWT, Kotlin, Ceylon, ClojureScript, ScalaJS and [any language that compiles to JavaScript](https://github.com/jashkenas/coffeescript/wiki/List-of-languages-that-compile-to-JS). + +So take your pick; the person who creates a plugin can use whatever language they prefer, so please contribute a [new plugin](http://hawt.io/contributing/index.html) :). + +The only real APIs a plugin needs to worry about are AngularJS (if you want to work in the core layout rather than just be an iframe), JSON (for some pretty trivial extension points such as adding new tabs), HTML and CSS. + +#### How can I add my new plugin? + +Check out [how plugins work](http://hawt.io/plugins/index.html). You can then either: + +* Fork this project and submit your plugin by [creating a Github pull request](https://help.github.com/articles/creating-a-pull-request) then we'll include your plugin by default in the hawtio distribution. +* Make your own WAR with your plugin added (by depending on the hawtio-web.war in your pom.xml) +* Host your plugin at some canonical website (e.g. with Github pages) then [submit an issue](https://github.com/hawtio/hawtio/issues?state=open) to tell us about it and we can add it to the plugin registry JSON file. + +#### How can I reuse those awesome AngularJS directives in my application? + +We hope that folks can just write plugins for hawtio to be able to reuse all the various [plugins](http://hawt.io/plugins/index.html) in hawtio. + +However if you are writing your own stand alone web application using AngularJS then please check out the [Hawtio Directives](http://hawt.io/directives/) which you should be able to reuse in any AngularJS application http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/README.md ---------------------------------------------------------------------- diff --git a/console/app/site/README.md b/console/app/site/README.md new file mode 100644 index 0000000..51bce73 --- /dev/null +++ b/console/app/site/README.md @@ -0,0 +1,30 @@ + +Don't cha wish your console was [hawt like me?](http://www.youtube.com/watch?v=YNSxNsr4wmA) I'm hawt so you can stay cool + +**[hawtio](http://hawt.io)** is a lightweight and [modular](http://hawt.io/plugins/index.html) HTML5 web console with [lots of plugins](http://hawt.io/plugins/index.html) for managing your Java stuff + +[View Demos](http://hawt.io/articles/index.html) +[Get Started Now!](http://hawt.io/getstarted/index.html) + +**hawtio** has [lots of plugins](http://hawt.io/plugins/index.html) such as: a git-based Dashboard and Wiki, [logs](http://hawt.io/plugins/logs/index.html), [health](http://hawt.io/plugins/health/index.html), JMX, OSGi, [Apache ActiveMQ](http://activemq.apache.org/), [Apache Camel](http://camel.apache.org/), [Apache OpenEJB](http://openejb.apache.org/), [Apache Tomcat](http://tomcat.apache.org/), [Jetty](http://www.eclipse.org/jetty/), [JBoss](http://www.jboss.org/jbossas) and [Fuse Fabric](http://fuse.fusesource.org/fabric/) + +You can dynamically [extend hawtio with your own plugins](http://hawt.io/plugins/index.html) or automatically [discover plugins](http://hawt.io/plugins/index.html) inside the JVM. + +The only server side dependency (other than the static HTML/CSS/JS/images) is the excellent [Jolokia library](http://jolokia.org) which has small footprint (around 300Kb) and is available as a [JVM agent](http://jolokia.org/agent/jvm.html), or comes embedded as a servlet inside the **hawtio-default.war** or can be deployed as [an OSGi bundle](http://jolokia.org/agent/osgi.html). + + +## Want to hack on some code? + +We love [contributions](http://hawt.io/contributing/index.html)! + +* [Articles and Demos](http://hawt.io/articles/index.html) +* [FAQ](http://hawt.io/faq/index.html) +* [Change Log](http://hawt.io/changelog.html) +* [Hawtio Directives](http://hawt.io/directives/) +* [How to contribute](http://hawt.io/contributing/index.html) +* [How to build the code](http://hawt.io/building/index.html) +* [How to get started working on the code](http://hawt.io/developers/index.html) +* [Community](http://hawt.io/community/index.html) + +Check out our [huboard](https://huboard.com/hawtio/hawtio#/) for prioritizing issues. + http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/doc/Articles.md ---------------------------------------------------------------------- diff --git a/console/app/site/doc/Articles.md b/console/app/site/doc/Articles.md new file mode 100644 index 0000000..783ca27 --- /dev/null +++ b/console/app/site/doc/Articles.md @@ -0,0 +1,35 @@ +# Demos + +* <a href="https://vimeo.com/album/2635012"; title="a library of demo videos using hawtio with JBoss Fuse">various demos of using hawtio, ActiveMQ and Camel inside JBoss Fuse</a> by [James Strachan](http://macstrac.blogspot.co.uk/). JBoss Fuse 6.1 or later uses hawtio for its management console; so all these demos are really hawtio demos (in terms of the console). +* <a href="http://vimeo.com/80625940"; title="Demo of Fuse 6.1 with Apache Camel and hawtio on OpenShift">Demo of Fuse 6.1 with Apache Camel and hawtio on OpenShift</a> by [James Strachan](http://macstrac.blogspot.co.uk/) showing how to get started using <a href="http://www.jboss.org/products/fuse";>JBoss Fuse</a> 6.1 Early Access release on OpenShift for creating integration solutions based on Apache Camel in the hybrid cloud (via <a href="https://www.openshift.com/products/online";>OpenShift Online</a> for the public cloud or <a href="https://www.openshift.com/products/enterprise";>OpenShift Enterprise</a> for on premise, or a combination of both). +* <a href="https://vimeo.com/68442425"; title="see a demo of provisioning Fuse containers, viewing, editing, debugging and provisioning Camel routes using Fuse Fabric with the hawtio console">CamelOne keynote 2013</a> by [James Strachan](http://macstrac.blogspot.co.uk/) showing the create, view, edit debug and provision of Camel routes using Fuse Fabric with the hawtio +* <a href="https://www.youtube.com/watch?v=sL6tlEv-mxQ";>demo of FMC and hawtio with Fuse Fabric</a> + +## Videos on hawtio + +The following videos has been found on the web about hawtio. If you find any others please [let us know](http://hawt.io/community/index.html) or [raise an issue](https://github.com/hawtio/hawtio/issues?state=open) and we'll add it to the list. + +* [hawtio - the Extensive console](https://www.youtube.com/watch?v=Bxgk9--_WzE) by Stan Lewis, at [DevNation 2014](http://www.devnation.org/) presenting how you can extend and build your own plugins to hawtio. Highly recommended if you want to build custom plugins. +* Hawtio on Talend ESB part [1](https://www.youtube.com/watch?v=lzdgxcHwfcY), [2](https://www.youtube.com/watch?v=_vjp8rg1DNQ), [3](https://www.youtube.com/watch?v=uJqG2JbXfkM) by [Robin Huiser](http://nl.linkedin.com/in/robinhuiser) + +## Articles on using hawtio + +The following articles have been found on the web about hawtio. If you find any others please [let us know](http://hawt.io/community/index.html) or [raise an issue](https://github.com/hawtio/hawtio/issues?state=open) and we'll add it to the list. + +* [Hawtio + ActiveMQ](http://www.christianposta.com/blog/?p=315) by [Christian Posta](http://www.christianposta.com/) +* [Hawtio & Apache Jclouds](http://iocanel.blogspot.co.uk/2013/07/hawtio-apache-jclouds.html) by [Ioannis Canellos](http://iocanel.blogspot.co.uk/) +* [Apache Camel web dashboard with hawtio](http://www.davsclaus.com/2013/04/apache-camel-web-dashboard-with-hawtio.html) by [Claus Ibsen](http://www.davsclaus.com) +* [introducing the Apache Camel based open source iPaaS](http://macstrac.blogspot.co.uk/2013/06/introducing-apache-camel-based-open.html) by [James Strachan](http://macstrac.blogspot.co.uk/) +* [Monitoring Camel Application](http://bushorn.com/monitoring-camel-application/) by [Gnanaguru](http://bushorn.com/author/gnanagurus/) +* [Hawtio, la console web polyvalente](http://blog.zenika.com/index.php?post/2014/01/07/HawtIO-la-console-web-polyvalente) by Gérald Quintana (in French) with a great overview of hawtio (note: Google can translate the page into readable english) +* [Hawtio, écrire un plugin](http://blog.zenika.com/index.php?post/2014/01/14/HawtIO-ecrire-un-plugin) by Gérald Quintana (in French) the second part on writing a plugin (note: Google can translate the page into readable english) +* [Hawtio authentication with LDAP](http://jcordes73.blogspot.de/2014/03/hawtio-authentication-with-ldap-on.html) by Jochen Cordes with a blog series how to use LDAP authentication with hawtio running on Tomcat 7, JBoss Fuse, and JBoss EAP. +* [Installing hawtio as web console for ActiveMQ](http://sensatic.net/activemq/activemq-and-hawtio.html) by Dejan Bosanac shows how to install hawtio as the web console in Apache ActiveMQ. Dejan also demonstrates how you can remote connect from hawtio to any ActiveMQ broker. +* [HawtIO on JBoss Wildfly 8.1 -- step by step](http://www.christianposta.com/blog/?p=403) by [Christian Posta](http://www.christianposta.com/) How to get HawtIO running and secured on JBoss Wildfly Application Server 8.1 +* [HawtIO on OpenShift](http://jimmidyson.github.io/hawtio-on-OpenShift/) by Jimmi Dyson, how to run Apache Tomcat on OpenShift Online and install hawtio into the Tomcat. +* [Hawtio on JBoss EAP 6](http://jcordes73.blogspot.de/2014/12/deploying-hawtio-on-jboss-eap-6.html) by Jochen Cordes how to deploy Hawtio on JBoss EAP 6 + +## Developer articles + +* [Creating a directive in hawtio](http://www.wayofquality.de/open%20source/hawtio/creating-a-hwatio-directive/) by [Andreas Gies](http://www.wayofquality.de/index.php/blog) +* [Using a data factory to encapsulate backend data in hawtio](http://www.wayofquality.de/open%20source/hawtio/using-a-datafactory-in-hawtio/) by [Andreas Gies](http://www.wayofquality.de/index.php/blog) http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/doc/CodingConventions.md ---------------------------------------------------------------------- diff --git a/console/app/site/doc/CodingConventions.md b/console/app/site/doc/CodingConventions.md new file mode 100644 index 0000000..a87daa9 --- /dev/null +++ b/console/app/site/doc/CodingConventions.md @@ -0,0 +1,63 @@ +# Code Conventions + +While we don't want to be too anal about coding styles, we are trying to adopt conventions to help make things easier to find, name, navigate and use. + +Here's a few of them we've found over time... + +## TypeScript / JavaScript code style + +* Use 2 spaces for TypeScript / JavaScript / JSON / HTML / CSS / XML please + +## Angular Controllers + +* for AngularJS Controllers, setup all the $scope properties and functions at the top of the controller code please +* then put all the associated nested functions below; so its easier to grok the $scope by looking at the top of the file +* its good practice to put a plugin in a TypeScript / JavaScript module +* when sharing functions across controllers, pop them into the module as exported functions; they could be handy outside the module too. +* common file names for plugin $foo: + * $fooPlugin.ts is the plugin + * $fooHelpers.ts containers the exported helper functions. + +## Plugin File Layout + +Each plugin should have its own directory tree with optional child folders called: + +* `html` for any HTML partials or layouts +* `js` for JavaScript / TypeScript / CoffeeScript code +* `img` for images +* `css` for CSS / SASS / SCSS files +* `doc` for user documentation (in `doc\help.md` and other files) and developer documentation (`doc\developer.md`) which then plugins into the help system + +For a plugin called `foo` Inside the `foo/js` folder we typically use a file called `fooPlugin.ts` to define the plugin. This is the file which creates an AngularJS module and defines any associated factories, services, directives, filters, routes, etc. + +Each controller we typically put into a file; usually using a lowercase version of the controller name (usually omitting the 'Controller' suffix since other than the `fooPlugin.ts` file most of the source is just controllers). + +For general helper functions we tend to have a file called `fooHelpers.ts`. + +## URI Templates + +It is common to use URI templates to denote different views. We try follow these conventions... + +For a given entity or resource `Foo` consider using these URI templates: + + * `/foo` for the top level view of all the foos to view/search `foo`s + * `/foo/edit` the edit page for `foo`s if that makes sense + * `/foo/id/:id` the URI template of a single `foo` looking up by uniqueID + * `/foo/idx/:index` the URI template of a single `foo` looking up by index. So `/foo/idx/0` could redirect to `/foo/id/abc` to show the first in a collection + +Having the extra level of indirection between `/foo` and the id of a `foo` item; lets us have other ways to navigate the foo collection; by name/location/country or whatever. + +This avoids us having `/foo` and `/foos` top level paths and having to figure out a nice URI for plural of foo and makes it easier to group all `foo` URIs by `path.startsWith("/foo")` + +## UI Conventions + +When showing buttons we tend to use the order Start, Pause, Stop, Refresh, Delete (remove where applicable) so that the more serious options like Delete are at the far end and the easier options (start/pause) are closer together. + +We are currently using these [Font Awesome icons](http://fortawesome.github.io/Font-Awesome/) by default + + * start: green icon-play-circle + * pause: icon-pause + * stop: orangle icon-off + * refresh: icon-refresh + * delete: icon-remove + http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/3c9a22b4/console/app/site/doc/Community.html ---------------------------------------------------------------------- diff --git a/console/app/site/doc/Community.html b/console/app/site/doc/Community.html new file mode 100644 index 0000000..d6b3c98 --- /dev/null +++ b/console/app/site/doc/Community.html @@ -0,0 +1,92 @@ +<div id="content-header"> + <div class="container"> + <h1>Community</h1> + </div> +</div> +<div class="container"> + <div id="content"> + <div id="intro"> + <p>Welcome to the <b>hawtio</b> community! We <a href="../Contributing.md">love contributions</a>!</p> + + <p><a class="btn btn-primary" href="../Contributing.md">How To Contribute</a></p> + + <p>Please dive in wherever takes your fancy! It's <i>hawt</i> but stay cool!</p> + </div> + + <div class="section"> + <h2 class="icon github"><img src="app/site/doc/images/octocat_social.png"/> Issue Tracker</h2> + + <p>The project tracks bugs, feature requests, and other issues through the Github issue tracking system.</p> + + <p><a class="btn btn-primary" href="https://github.com/hawtio/hawtio/issues";>hawtio issue tracker</a> + </p> + + <p>To file new issues or comment on existing issues you need to register for a <a href="http://github.com/";>Github + account</a> which is quick and easy! + </p> + </div> + + <div class="section"> + <h2 class="icon twitter"><img style="max-width: 48px; max-height: 48px;" src="app/site/doc/images/twitter.png"/> + Twitter</h2> + + <p>We invite you to follow us on twitter</p> + + <p><a class="btn btn-primary" href="https://twitter.com/hawtio"; title="follow @hawtio on twitter">@hawtio on twitter</a></p> + + </div> + + <div class="section"> + <h2 class="icon forum"><img style="max-width: 48px; max-height: 48px;" src="app/site/doc/images/groups.png"/> + Mailing List</h2> + + <p>We prefer to use the <a href="https://github.com/hawtio/hawtio/issues";>issue tracker</a> for dealing with ideas + and + issues, but if you just want to chat about all things hawtio please join us on the mailing list. + Its pretty low volume though as we love <a href="https://github.com/hawtio/hawtio/issues";>github issues</a></p> + + <p><a class="btn btn-primary" href="https://groups.google.com/forum/#!forum/hawtio";>hawtio mailing + list</a> + </p> + </div> + + <div class="section"> + <h2 class="icon chat"><img style="max-width: 48px; max-height: 48px;" src="app/site/doc/images/irc.png"/> + Chat (IRC)</h2> + + <p>We invite you to join us in the <b>#hawtio</b> channel on <b>irc.freenode.net</b> to chat about hawtio</p> + + <p>This channel is logged to <a class="btn btn-primary" + href="http://transcripts.jboss.org/channel/irc.freenode.org/%23hawtio/2014/index.html";>transcripts.jboss.org</a> + by JBossBot. The JBossBot is also present to expand issue numbers from the issue tracker.</p> + </div> + + <div class="section"> + <h2 class="h2"><img style="max-width: 48px; max-height: 48px;" src="app/site/doc/images/stackoverflow.png"/> + Stack Overflow + </h2> + + <p>We also keep an eye out on Stack Overflow for questions which makes it really easy to find answers to questions + and commonly found problems. Though if you're running into an issue please use our + <a href="https://github.com/hawtio/hawtio/issues";>issue tracker</a> instead.</p> + + <p> + <a class="btn btn-primary" href="http://stackoverflow.com/questions/tagged/hawtio";>Stack Overflow</a> + </p> + </div> + + <div class="section"> + <h2 class="h2"><img src="app/site/doc/images/octocat_social.png"/> Source Repository</h2> + + <p>All the hawtio source code is managed using the distributed version system <a href="http://git-scm.com";>git</a> + and hosted on <a href="http://github.com/";>github</a>.</p> + + <p><a class="btn btn-primary" href="http://github.com/hawtio/hawtio";>hawtio @ github</a></p> + + + <p>Both git and Github are awesome for collaboration! To make improvements or bug fixes to the hawtio project, + simply + fork the project, commit your changes, and send a pull request.</p> + </div> + </div> +</div> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
