You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by fl...@apache.org on 2012/10/25 03:24:31 UTC
svn commit: r1401940 - in /stanbol/site/trunk: content/production/ templates/
Author: florent
Date: Thu Oct 25 01:24:31 2012
New Revision: 1401940
URL: http://svn.apache.org/viewvc?rev=1401940&view=rev
Log:
STANBOL-789 add some documentation under 'production'
Added:
stanbol/site/trunk/content/production/
stanbol/site/trunk/content/production/file-bundle-configuration.mdtext
stanbol/site/trunk/content/production/index.mdtext
stanbol/site/trunk/content/production/partial-updates.mdtext
stanbol/site/trunk/content/production/your-launcher.mdtext
Modified:
stanbol/site/trunk/templates/sidenav.mdtext
Added: stanbol/site/trunk/content/production/file-bundle-configuration.mdtext
URL: http://svn.apache.org/viewvc/stanbol/site/trunk/content/production/file-bundle-configuration.mdtext?rev=1401940&view=auto
==============================================================================
--- stanbol/site/trunk/content/production/file-bundle-configuration.mdtext (added)
+++ stanbol/site/trunk/content/production/file-bundle-configuration.mdtext Thu Oct 25 01:24:31 2012
@@ -0,0 +1,36 @@
+Title: File based bundle configuration
+
+* During development and deployment process it can be a pain have to reconfigure all your bundles in the Felix web interface.
+
+* Stanbol offer the bundleconfig mechanism that allow you to save this configurations and apply them automatically.
+
+* A bundleconfig artifact is a Maven project with this structure :
+<code>
+mybundlelistFolder
+ |
+ |- pom.xml
+ |- src
+ |- main
+ |- resources
+ |- config
+ |- config1.conf
+ |- config2.conf
+ |- ....
+<code>
+
+* The pom.xml has nothing special. You can copy [this one](https://svn.apache.org/repos/asf/stanbol/trunk/data/defaultconfig/pom.xml) for example and only adapt group and artifact ID to suit your project naming convention.
+
+* The configurations are held by files in the src/main/resources/config folder.
+* This configurations files need to respect this naming convention :
+ * {bundleArtifactID}-{uniqueID}.conf, where {uniqueID} can be anything.
+ * for example a configuration file with this name "org.apache.stanbol.enhancer.engines.keywordextraction.engine.KeywordLinkingEngine-entityhub.config" will be used to configure the Keyword Linking Engine bundle.
+
+* The content of this configuration files are key-values pairs where :
+ * the key is the fully qualified name of the property (example : org.apache.stanbol.enhancer.engines.keywordextraction.maxSuggestions)
+ * and the value is a string that contains the needed value for the property. To ensure a correct binding between the value in the configuration file and the property's Java type, this conventions are helpfull :
+ * *"my value"* : for String properties
+ * *B"false"* : for boolean properties
+ * *I"5"* : for int properties
+ * *["value1","value2"]* : for String collection properties
+
+* Of course, this bundleconfig bundle can be added to your [custom launcher and bundlelist](your-launcher.html), just be careful to define a higher startlevel to your bundleconfig than the configured bundles' startlevel.
Added: stanbol/site/trunk/content/production/index.mdtext
URL: http://svn.apache.org/viewvc/stanbol/site/trunk/content/production/index.mdtext?rev=1401940&view=auto
==============================================================================
--- stanbol/site/trunk/content/production/index.mdtext (added)
+++ stanbol/site/trunk/content/production/index.mdtext Thu Oct 25 01:24:31 2012
@@ -0,0 +1,10 @@
+Title: Production
+
+This document provide some informations related to the "Stanbol in production" topic.
+
+* [Create your launcher](your-launcher.html) : Stanbol stack do many things, and result to a big launcher when all is included. Comming to production, not all Stanbol features are in use, and the requirement to get a "just what I need" Stanbol instance come into play. This document give some pointers to get your launcher.
+
+* [Automatic bundle configuration](file-bundle-configuration.html) : Stanbol is a simple hightly configurable product, thanks to the Felix web interface and the OSGI bundle. But how to safely keep this configurations from old to new version ? Get a configured server from the first launch ?
+
+* [Partial dynamic server updates](partial-updates.html) : Stanbol fully use the hot bundle update OSGI feature. Of course, you can do this with the Felix webAdmin. This web interface can be less effective when update are hudge or frequent.
+
Added: stanbol/site/trunk/content/production/partial-updates.mdtext
URL: http://svn.apache.org/viewvc/stanbol/site/trunk/content/production/partial-updates.mdtext?rev=1401940&view=auto
==============================================================================
--- stanbol/site/trunk/content/production/partial-updates.mdtext (added)
+++ stanbol/site/trunk/content/production/partial-updates.mdtext Thu Oct 25 01:24:31 2012
@@ -0,0 +1,15 @@
+Title: Hot partial Stanbol update
+
+* One of the biggest "cool feature" of OSGI is the capability to update pieces of the server without restart it.
+
+* Felix web interface allow you to do this with click, but it's not always comfortable to do this way (production environment, numerous bundles to update,...)
+
+* The Apache Sling File Provider allow you to define a folder, where you just have to drop/update/delete your bundle to get your server in sync.
+
+* Follow this two step procedure to enjoy this feature :
+
+0. Install the "Sling File Provider" Bundle (not needed as this is included by default in Stanbol)
+1. Configure the "sling.fileinstall.dir" property: You can add this to the "{stanbol-working-dir}/stanbol/sling.properties file" or parse it as a system property '-Dsling.fileinstall.dir={path-to-dir}' when you start stanbol.
+2. Create the referenced Folder on you file system.
+
+* Note : this procedure was extracted for a Rupert Westenthaler's mail. Thanks to him to spot it !
Added: stanbol/site/trunk/content/production/your-launcher.mdtext
URL: http://svn.apache.org/viewvc/stanbol/site/trunk/content/production/your-launcher.mdtext?rev=1401940&view=auto
==============================================================================
--- stanbol/site/trunk/content/production/your-launcher.mdtext (added)
+++ stanbol/site/trunk/content/production/your-launcher.mdtext Thu Oct 25 01:24:31 2012
@@ -0,0 +1,117 @@
+Title: Build your launcher
+
+# Principle
+
+* A Stanbol launcher is a big set of bundles that work together and provide features packages (EntityHub, ContentHub, Enhancer,...).
+* Each features package need a list of bundles to work smoothly.
+* Thanks for Stanbol design, you can have in your server only some of the proposed features package (for example only the EntityHub and Enhancer, without others features). You only need all required bundles for the features package you want.
+
+* Identify and manually add all feature's required bundles can be pain and long.
+* Hopefully, the *bundlelist* mechanism allow the creation of specific set of bundles that will be added together to the launcher and started in the right way.
+
+* Stanbol launcher's use this bundlelist mechanism. Let's dive into the details.
+
+# Use existing bundlelists to build your launcher
+
+## Dependencies to bundlelist
+
+* Bundlelist are in fact just jar. So you just need to declare them as dependencies in you launcher pom.xml to get the feature package and all required bundle for it.
+* For example, if you want the entityHub feature in you server, you only need to add this dependency to your launcher pom.xml :
+<code>
+ <dependency>
+ <groupId>org.apache.stanbol</groupId>
+ <artifactId>org.apache.stanbol.entityhub.bundlelist</artifactId>
+ <version>0.11.0-SNAPSHOT</version>
+ <type>partialbundlelist</type>
+ <scope>provided</scope>
+ </dependency>
+</code>
+
+* please note the <type>partialbundlelist</type> of the dependency.
+* Also in actual Stanbol code base you can easily detect feature package bundlelist as their artifactId has the structure org.apache.stanbol.{feature-name}.bundlelist
+
+## Build *your* launcher
+
+* Let's imagine that for now you only use EntityHub and Enhancer features packages.
+* The more simple way to get you custom launcher is to :
+ * copy the [full launcher folder](http://svn.apache.org/repos/asf/stanbol/trunk/launchers/full/) to "my-launcher" folder
+ * open the my-launcher/pom.xml and change the <artifactId>org.apache.stanbol.launchers.full</artifactId> node to <artifactId>my.launcher</artifactId>
+
+* Then you get a custom launcher, but still with all the Stanbol features.
+* To only keep the features you want (EntityHub and Enhancer in this example), scroll down to the <dependencies> part and remove all **but** dependencies labelled with :
+ * "The Apache Stanbol lauchpad" and "maven-launchpad-plugin builds on the launchpad.base app" : dependencies required for the launcher to launch
+ * "OSGi Framemework Bundle List" : provide all bundle for the OSGI in Stanbol
+ * "Stanbol Commons Bundle List" : contains all the feature's shared bundles
+ * "Stanbol Data Bundle List" : keep it only if you plan to use dataset provided by Stanbol in the EntityHub
+ * "Stanbol Enhancer Bundle List" : will provide all required bundles for the enhancer feature
+ * "Stanbol Entityhub Bundle List" : will provide the EntityHub feature
+
+* At the end, your <dependencies> section only contains this 7 dependencies.
+* Do an "mvn clean install"
+* Move to you target folder and launch the my-launcher.jar.
+* You get a running Stanbol with only the features you need.
+
+# Create your own bundlelist
+
+* Going to the road of Stanbol development and use, you will just not only need to cherry pick Stanbol's features package you want but also provide your own set of bundles directly to the launcher during the building phase.
+
+* The bundlelist mechanism is the perfect and simple way to include your list of bundles into your launcher !
+
+## Build **your** bundlelist dependency
+
+* Bundlelist (or partialbundlelist) artifact is a really simple Maven project that rely on this structure :
+<code>
+mybundlelistFolder
+ |
+ |- pom.xml
+ |- src
+ |- main
+ |- bundles
+ |- list.xml
+<code>
+
+* You only need to define 2 files :
+ * pom.xml : really simple you can copy-paste the [Enhancer bundlelist](http://svn.apache.org/repos/asf/stanbol/trunk/enhancer/bundlelist/pom.xml) one and only change the groupId and artifactId properties to suit you need. All the magic here is contained in <packaging> property.
+ * list.xml : this file will contains information about the bundles you want to include. This file has a simple structure :
+<code>
+<bundles>
+ <startlevel level="L0">
+ <bundle>
+ ...Maven groupId,artifactID and version properties...
+ </bundle>
+ <bundle>
+ ...another Maven's dependency information...
+ </bundle>
+ </startlevel>
+ <startlevel level="L1">
+ ... anothers bundles nodes...
+ </startlevel>
+</bundles>
+</code>
+
+* Start level is an important things to keep in mind as the value of the "level" property will determine when your bundle is started during the server launch.
+ * So, if your bundle require some other services to be up and running, be sure to define a higher start level to your bundle that the ones of the required services.
+
+* You can find and extensive bundlelist definition for inspiration in the [Enhancer bundlelist list.xml](http://svn.apache.org/repos/asf/stanbol/trunk/enhancer/bundlelist/src/main/bundles/list.xml).
+
+## Add **your** bundlelist to **your** launcher
+
+* Let's says that your bundlelist pom.xml contains :
+<code>
+ <groupId>com.example</groupId>
+ <artifactId>my.bundlelist</artifactId>
+ <version>0.10.0-SNAPSHOT</version>
+ <packaging>partialbundlelist</packaging>
+</code>
+
+* Bring your bundles into your launcher only require you to edit my-launcher/pom.xml and add in <dependencies> section, this one :
+<code>
+<dependency>
+ <groupId>com.example</groupId>
+ <artifactId>my.bundlelist</artifactId>
+ <version>0.10.0-SNAPSHOT</version>
+ <packaging>partialbundlelist</packaging>
+</dependency>
+</code>
+
+* Stanbol is now all yours !
Modified: stanbol/site/trunk/templates/sidenav.mdtext
URL: http://svn.apache.org/viewvc/stanbol/site/trunk/templates/sidenav.mdtext?rev=1401940&r1=1401939&r2=1401940&view=diff
==============================================================================
--- stanbol/site/trunk/templates/sidenav.mdtext (original)
+++ stanbol/site/trunk/templates/sidenav.mdtext Thu Oct 25 01:24:31 2012
@@ -5,6 +5,7 @@
- [Usage Scenarios](/docs/trunk/scenarios.html)
- [Components](/docs/trunk/components)
- [Development](/development/)
+ - [Production](/production/)
# Project
- [Mailing Lists](/docs/trunk/mailinglists.html)