Merge branch 'feature/improved-configuration' into 'develop'

Feature/improved configuration



See merge request !1

README.md

@@ -1,26 +1,79 @@
 # karaf-runner
 
+Cross-platform (actually not tested) utility tool for running Apache Karaf
+
+## Features
+
+ - Locate and pre-install features/kars
+ - Handle cross-project dependencies
+ - Copy configuration based on environment and project
+ - Handling of multiple Karaf images/version/assemblies
+ - Locating and running custom Karaf assemblies built with maven karaf-assembly plugin
+
+## Quick usage example
+
+Simple as pie - just run the following:
+
+```bash
+karaf-runner run from-kars --environment dev
+# or if you want to run your project from features:
+karaf-runner run from-features
+# or maybe you want to run custom Karaf assembly?
+karaf-runner run from-assembly
+```
+
+For more see sections below
+
 ## Installation
 
+### Unix-like systems
+
+#### 1
+
 ```bash
-SOME_PATH_WHERE_YOU_WANT_KARAF_RUNNER_TO_BE=/usr/local/bin
-PATH_WHERE_TEMPLATES_WOULD_LIVE=/usr/local/etc/karaf
-mvn clean install
-echo '#!'"$(which java)"' -jar -Dkaraf-runner.templates-dir="${PATH_WHERE_TEMPLATES_WOULD_LIVE}"' >> target/karaf-runner
-cat target/karaf-runner.jar >> target/karaf-runner
-chmod +x target/karaf-runner
-
-cp target/karaf-runner $SOME_PATH_WHERE_YOU_WANT_KARAF_RUNNER_TO_BE # recommended to use /usr/local/bin
+sudo ./install [--installation-path /usr/local/bin] [--configuration-file /usr/local/etc/karaf-runner/config]
 ```
 
- - `$SOME_PATH_WHERE_YOU_WANT_KARAF_RUNNER_TO_BE` - Location where karaf-runner would be installed
- - `${PATH_WHERE_TEMPLATES_WOULD_LIVE}` - Location where karaf-runner templates would live, if not set (omitted at all) uses `/usr/local/etc/karaf`
-
-That was just building project, making jar to be executable and passing default property to each execution of jar.
+#### 1.1 (optional)
+
+You may want to configure where your configuration templates and images would live
+
+```
+# /usr/loca/etc/karaf-runner/config
+
+templatesPath += /usr/local/etc/karaf-runner
+imagesPath += /opt/karaf-runner/images
+```
+
+#### 2
+
+```bash
+sudo karaf-runner image install /path/to/directory/with/karaf-assembly
+```
+
+Also you can simply `cd` into directory with assembly and run command without path.
+(Actually path needn't to be direct parent of assembly, any parent in hierarchy is allowed,
+ex. /path/to is also accepted)
+
+#### 3
+
+It's time to run it!
+
+### Windows
+
+Windows users MUST SUFFER :smiling_imp:
+
+OK, it's just a joke: just build it with maven and at every execution of karaf-runner
+pass `-Dkaraf-runner.configurationFile=PATH_TO_YOUR_CONFIGURATION`, every thing else is
+backward compatible with **Unix-like**-section, just replace prefix according to following table:
+
+| Unix           | Windows         |
+|----------------|-----------------|
+| /usr/local/etc | %HOME%\\.config |
+| /opt           | %HOME%\\.opt    |
+
+Also you can use configuration file to place your templates and images where you want
 
-Karaf image (assembly) must be located at `/opt/karaf-$KARAF_VERSION.0`, where `$KARAF_VERSION` is major version of karaf,
-default version for karaf is 3
-
 ## Template hierarchy
 
 ```
@@ -55,10 +108,11 @@ default version for karaf is 3
 ## Configuration
 
 Every project dir may contain `.karaf-runner.project` file with karaf-runner configuration for that project.
-Configuration consists of 2 parts:
+Configuration consists of 3 parts:
 
  1. Projects description - contains list of project names, all of them would be used
  2. Dependencies description - contains paths of projects on which current depends
+ 3. Image - you can specify image to use instead of "default" as default one 
 
 Karaf-runner would scan also dependent configurations, so if your project (A) depends on project B, depending on project C
 with names: C and D, you'll have project names as following: C, D, B, A
@@ -72,11 +126,16 @@ Format is much like qmake's .pro files, except of the only operator supported is
 Keys:
 
  - `projects`
+ - `project` - alias for `projects`
  - `dependencies`
+ - `dependency` - alias for `dependencies`
+ - `images`
+ - `image` - alias for `images`
 
 #### Example
 
 ```
+image = caterpillar
 projects += pim
 projects += pom
 dependencies += ../ssm
@@ -85,25 +144,33 @@ dependencies += ../ssm
 ## Usage
 
 ```
-  karaf-runner <install|run|image|get-path|shutdown> {arguments} [options]
+Usage
+  karaf-runner <install|run|image|get-path|shutdown|help> {arguments} [options]
 
 Modules
+  help                              Show this help message
   get-path [OPTIONS]                Get path where karaf currently installed
     Options:
-      --karaf-version=<VERSION>, -k <VERSION> Specifies version of karaf
-                                              Defaults to "3" (/opt/karaf-3.0)
+      --image=<IMAGE_NAME>, -i <IMAGE_NAME>   Specifies image name
+                                              Defaults to "default" (/opt/karaf-runner/images/$IMAGE_NAME)
 
       --raw, -r                               Just show path, without user message (useful for scripts)
 
   install <MODE> [OPTIONS]          Installs karaf of specified version
     Options:
-      --karaf-version=<VERSION>, -k <VERSION>    Specifies version of karaf
-                                                 Defaults to "3" (/opt/karaf-3.0)
+      --image=<IMAGE_NAME>, -i <IMAGE_NAME>      Specifies image name
+                                                 Defaults to "default" (/opt/karaf-runner/images/$IMAGE_NAME)
+
+      --project-name=<PROJECT_NAME>,             Explicitly specify project names, repeat option for
+      -p <PROJECT_NAME>                          setting more than one project name
+
+      -P                                         Disable ask for project name and don't copy project templates
 
       --templates-path=<PATH>, -T <PATH>         Specify path, where templates live
                                                  Defaults to /usr/local/etc/karaf
 
-      --environment=<ENV>, --env=<ENV>, -e <ENV> Specifies environment of configuration, required
+      --environment=<ENV>, --env=<ENV>, -e <ENV> Specifies environment of configuration, if not set
+                                                 doesn't copy environment related templates
 
       --use-assembly, -A                         Tells not to use base image and search
                                                  for assembly dir instead (don't affects assembly mode)
@@ -117,30 +184,37 @@ Modules
 
   shutdown [OPTIONS]                Drop currently installed karaf
     Options:
-      --karaf-version=<VERSION>, -k <VERSION>  Specifies version of karaf
-                                               Defaults to "3" (/opt/karaf-3.0)
+      --image=<IMAGE_NAME>, -i <IMAGE_NAME>    Specifies image name
+                                               Defaults to "default" (/opt/karaf-runner/images/$IMAGE_NAME)
 
   image <MODE> [OPTIONS]            Manipulate image
     Options:
-      --karaf-version=<VERSION>, -k <VERISON> Specifies version of karaf
-                                              Defaults to "3" (/opt/karaf-3.0)
+      --image=<IMAGE_NAME>, -i <IMAGE_NAME>   Specifies image name
+                                              Defaults to "default" (/opt/karaf-runner/images/$IMAGE_NAME)
 
     Arguments (MODES):
       drop-cache           Drop image cache (use it when you've updated any base karaf image)
                            If image was updated with karaf-runner it is called automatically
       update [IMAGE_PATH]  Replace current image with specified one (default path is $PWD)
                            Path may be absolute path to image (assembly dir) or just one of
                            the parent paths
+      install [IMAGE_PATH] Alias for "update"
 
   run <MODE> [OPTIONS]              Install karaf and immediately run it
     Options:
-      --karaf-version=<VERSION>, -k <VERSION>    Specifies version of karaf
-                                                 Defaults to "3" (/opt/karaf-3.0)
+      --image=<IMAGE_NAME>, -i <IMAGE_NAME>      Specifies image name
+                                                 Defaults to "default" (/opt/karaf-runner/images/$IMAGE_NAME)
+
+      --project-name=<PROJECT_NAME>,             Explicitly specify project names, repeat option for
+      -p <PROJECT_NAME>                          setting more than one project name
+
+      -P                                         Disable ask for project name and don't copy project templates
 
       --templates-path=<PATH>, -T <PATH>         Specify path, where templates live
                                                  Defaults to /usr/local/etc/karaf
 
-      --environment=<ENV>, --env=<ENV>, -e <ENV> Specifies environment of configuration, required
+      --environment=<ENV>, --env=<ENV>, -e <ENV> Specifies environment of configuration, if not set
+                                                 doesn't copy environment related templates
 
       --use-assembly, -A                         Tells not to use base image and search
                                                  for assembly dir instead (don't affects assembly mode)

install

@@ -0,0 +1,85 @@
+#!/bin/bash
+
+installationPath=/usr/local/bin
+configurationFileProperty=""
+installHit=""
+
+function permission-check() {
+    file=$1
+    # Handle non-absolute paths
+    if ! [[ "$file" == /* ]] ; then
+        path=.
+    fi
+    dirname "$file" | tr '/' $'\n' | while read part ; do
+        path="$path/$part"
+        if ! [[ -x "$path" ]] ; then
+            echo "Forbidden"
+            return
+        fi
+    done
+    if ! [[ -w "$file" ]] ; then
+        echo "Forbidden"
+    fi
+}
+
+function show-help () {
+    echo "Usage: install [OPTIONS]"
+    echo " Options:"
+    echo "  --installation-path <DIRECTORY>    Path where karaf-runner binary would be installed"
+    echo "  --configuration-file <PATH>        Path where base karaf-runner configuration would be"
+}
+
+while [[ "$#" != "0" ]]; do
+    case "$1" in
+        "help" | "--help" | "-h")
+            show-help
+            exit
+        ;;
+        "--installation-path")
+            installationPath=$2
+            shift 2
+        ;;
+        "--configuration-file")
+            configurationFileProperty=" -Dkaraf-runner.configurationFile=$2"
+            shift 2
+        ;;
+        "install")
+            installHit="true"
+            shift 1
+        ;;
+        * )
+            echo "Unsupported option "'"'"$1"'"'
+            exit
+        ;;
+    esac
+done
+
+if [[ "$installHit" == "" ]]; then
+    echo "Error: no command specified"
+    show-help
+    exit
+fi
+
+installationPath=$(realpath $installationPath)
+
+if ! [[ -w $installationPath ]]; then
+    echo "You don't have permission to write to $installationPath"
+    exit
+fi
+
+cd $(dirname $0)
+
+echo "Building sources"
+(mvn clean install -Dmaven.test.skip=true >> /dev/null) || ( echo "Failed to build sources" && exit -1 )
+
+cd target
+
+echo "Building runnable binary"
+echo "#!/usr/bin/java -jar $configurationFileProperty" > karaf-runner
+cat karaf-runner.jar >> karaf-runner
+chmod +x karaf-runner
+
+echo "Installing to $installationPath"
+cp karaf-runner $installationPath
+
+echo "Installation complete"

pom.xml

@@ -43,6 +43,20 @@
       <version>2.4</version>
     </dependency>
 
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.12</version>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <version>3.3.0</version>
+      <scope>test</scope>
+    </dependency>
+
   </dependencies>
 
   <build>

src/main/java/run/smt/karafrunner/io/file-extensions.kt

@@ -5,4 +5,21 @@ import java.io.File
 
 fun File.copyToFile(file: File) {
     FileUtils.copyFile(this, file)
+}
+
+fun File.mkParentDirs(): Boolean {
+    return parentFile.mkdirp()
+}
+
+/**
+ * Create all necessary non-existent parent directories
+ * @return false if directories are still missing, true otherwise
+ *
+ * Name of method inspired by `mkdir -p`
+ */
+fun File.mkdirp(): Boolean {
+    if (exists()) {
+        return true
+    }
+    return mkdirs()
 }