README.adoc: removed 'status' section. Doesn't help in any way

= Minimal-J

Java - but small.

image::doc/frontends.png[]

Minimal-J applications are

* Responsive to use on every device
* Straight forward to specify and implement and therefor
* Easy to plan and manage

=== Idea

Business applications tend to get complex and complicated. Minimal-J prevents this by setting clear rules how an application should behave and how it should be implemented.

Minimal applications may not always look the same. But the UI concepts never change. There are no surprises for the user.

== Technical Features

* Independed to the used UI technology. Implementations for Web / Mobile / Desktop.
* ORM persistence layer for Maria DB or in memory DB. Transactions and Authorization supported.
* Small: The minimalj.jar is still < 1MB
* Very few dependencies
* Applications run standalone or in a servlet container.

== Documentation

* link:doc/user_guide.adoc[Minimal user guide] Good start point for user and programmer.
* link:doc/setup.adoc[Setup]
* link:doc/release_notes.adoc[Release Notes]

=== Topics and examples

The small examples are currently deployed on CloudFoundry as online demo. Please note that some features are still incomplete in the html frontend.

* link:example/001_EmptyApplication/doc/001.adoc[Empty Application] The smallest application link:http://minimalj-examples.cfapps.io/empty/[(online demo)]
* link:example/002_HelloWorld/doc/002.adoc[Hello World] The hello world and the greeting application link:http://minimalj-examples.cfapps.io/greeting/[(online demo)]
* link:example/003_Notes/doc/003.adoc[Notes] This application manages some notes link:http://minimalj-examples.cfapps.io/notes/[(online demo)]
* link:example/004_Library/doc/004.adoc[Library] Shows some more features of the framework link:http://minimalj-examples.cfapps.io/library/[(online demo)]
* link:example/005_Numbers/doc/005.adoc[Numbers] How integers and BigDecimals are used
link:http://minimalj-examples.cfapps.io/numbers/[(online demo)]
* link:example/006_Persistence/doc/006.adoc[Persistence] Introduction to the O/R mapping
* link:example/007_PetClinic/doc/007.adoc[PetClinic] Cover version of the Spring PetClinic application link:http://minimalj-examples.cfapps.io/petClinic/[(online demo)]
* link:doc/arch.adoc[Architecture] Explains the difference between client/server and frontend/backend
* link:doc/lists.adoc[Lists] How to use one to many relations in the data model
* link:doc/ui_content_and_components.adoc[UI details] Content, components and forms
* link:doc/authorization.adoc[Authorization] Security concepts and configuration

=== Real application
* https://github.com/BrunoEberhard/open-ech[Open-eCH]

= Minimal-J

Java - but small.

image::doc/frontends.png[]

Minimal-J applications are

* Responsive to use on every device
* Straight forward to specify and implement and therefor
* Easy to plan and manage

=== Idea

Business applications tend to get complex and complicated. Minimal-J prevents this by setting clear rules how an application should behave and how it should be implemented.

Minimal applications may not always look the same. But the UI concepts never change. There are no surprises for the user.

== Technical Features

* Independed to the used UI technology. Implementations for Web / Mobile / Desktop.
* ORM persistence layer for Maria DB or in memory DB. Transactions and Authorization supported.
* Small: The minimalj.jar is still < 1MB
* Very few dependencies
* Applications run standalone or in a servlet container.

== Status

Sometimes when I look at other frameworks I think Minimal-J is quite mature.
But at the moment it is still more of a personal research project. I still
feel free to change major points. There is no 1.0 version yet.

== Documentation

link:doc/user_guide.adoc[Minimal user guide] Good start point for user and programmer.

link:doc/setup.adoc[Setup]

link:doc/release_notes.adoc[Release Notes]

=== Topics and examples

The small examples are currently deployed on CloudFoundry as online demo. Please note that some features are still incomplete in the html frontend.

* link:example/001_EmptyApplication/doc/001.adoc[Empty Application] The smallest application link:http://minimalj-examples.cfapps.io/empty/[(online demo)]
* link:example/002_HelloWorld/doc/002.adoc[Hello World] The hello world and the greeting application link:http://minimalj-examples.cfapps.io/greeting/[(online demo)]
* link:example/003_Notes/doc/003.adoc[Notes] This application manages some notes link:http://minimalj-examples.cfapps.io/notes/[(online demo)]
* link:example/004_Library/doc/004.adoc[Library] Shows some more features of the framework link:http://minimalj-examples.cfapps.io/library/[(online demo)]
* link:example/005_Numbers/doc/005.adoc[Numbers] How integers and BigDecimals are used
link:http://minimalj-examples.cfapps.io/numbers/[(online demo)]
* link:example/006_Persistence/doc/006.adoc[Persistence] Introduction to the O/R mapping
* link:example/007_PetClinic/doc/007.adoc[PetClinic] Cover version of the Spring PetClinic application link:http://minimalj-examples.cfapps.io/petClinic/[(online demo)]
* link:doc/arch.adoc[Architecture] Explains the difference between client/server and frontend/backend
* link:doc/lists.adoc[Lists] How to use one to many relations in the data model
* link:doc/ui_content_and_components.adoc[UI details] Content, components and forms
* link:doc/authorization.adoc[Authorization] Security concepts and configuration

=== Real application
* https://github.com/BrunoEberhard/open-ech[Open-eCH]


README improved

README improved

= Mature Modular Meta-framework (mmm)

image:https://raw.github.com/m-m-m/mmm/master/src/site/resources/images/logo.png[logo]

*Welcome to the wonderful world of http://m-m-m.sourceforge.net/index.html[mmm]*

== mmm-persistence

Persistence infrastructure for DAOs based on JPA

=== Deprecated
This project is discontinued and not supported anymore.
Please consider using http://projects.spring.io/spring-data-jpa/[spring-data-jpa] or https://github.com/oasp/oasp4j/tree/develop/modules/jpa[oasp4j-module-jpa] instead.

= mmm-persistence
Persistence infrastructure for DAOs based on JPA

== Deprecated
This project is discontinued and not supported anymore.
Please consider using http://projects.spring.io/spring-data-jpa/[spring-data-jpa] or https://github.com/oasp/oasp4j/tree/develop/modules/jpa[oasp4j-module-jpa] instead.


README: update with new parameters

README: update with new parameters

= Baryonyx
Gauthier Quesnel <gauthier.quesnel@inra.fr>
v0.5.x, 2020-01-??
:toc:
:homepage: https://github.com/quesnel/baryonyx/

https://en.wikipedia.org/wiki/Baryonyx[Baryonyx] is an integer and binary linear
programming solver based on the http://www.cse.chalmers.se/~dag/[Dag Wedelin]
heuristic.

[width="15%"]
|============
| https://travis-ci.org/quesnel/baryonyx[image:https://travis-ci.org/quesnel/baryonyx.png?branch=master[Build Status]] | https://ci.appveyor.com/project/quesnel/baryonyx?branch=master[image:https://ci.appveyor.com/api/projects/status/github/quesnel/baryonyx?branch=master&svg=true[Build Status]]
|============

Copyright © 2017-2019 http://www.inra.fr/en[INRA]

The software is released under the MIT license. See the LICENSE file.

== Baryonyx

=== Requirements and recommended

* `cmake` (≥ 3.11)
* $$C++$$ compiler with $$C++17$$ support:
** `gcc` ≥ 7 (https://www.gnu.org/software/gcc/projects/cxx-status.html[notes])
** `clang` ≥ 5 (https://clang.llvm.org/cxx_status.html[notes])
** `visual studio 2017 15.9` with the latest patchs of 2018 (https://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2017-relnotes[notes])

For recent Debian GNU/Linux and Ubuntu derivatives (remove clang to
only use gcc):

[source,bash]
....
apt-get install build-essential cmake clang
....

For Windows, install the https://www.cmake.org[CMake program] and
Visual Studio 2017 (MSVC). You may also install the vcpkg program to
install nlopt and other dependencies.

* `nlopt` library - optimization library to automatic parametrization
 of the Baryonyx solver parameters.

=== First installation

First, we clone Baryonyx git repository and the submodule.

....
git clone https://github.com/quesnel/baryonyx.git
cd baryonyx
git submodule update --init --recursive
....

Default, Baryonyx provides a shared library `libbaryonyx-0.5.so` (with
hidden symbol), a static library `libbaryonyx-0.5.a` (all symbols are
public) and an executable `baryonyx-0.5`. To compile and install in
the default CMake install directory:

....
cd baryonyx
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make install
....

Previous command line install Baryonyx program and library into the
`/usr/local` prefix. If you install into another directory, you need
to define three environment variables (into your `.bashrc` or
equivalent). If you install into `$HOME/usr` for example, you need to
define in your `.bashrc`:

....
export PATH=$PATH:$HOME/usr/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/usr/lib
export PKG_CONFIG_PATH=$PKG_CONFIX_PATH:$HOME/usr/lib/pkgconfig
....

Then run the following commands:

....
cd baryonyx
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/usr ..
make install
....

To override the default build flags, remove the `CMAKE_BUILD_TYPE`
parameter and override the `CXXFLAGS` as follow:

....
export CXX=g++-8
export CXXFLAGS='-Wall -Wextra -Werror -ftree-vectorize -mmmx -msse -msse2 -msse3 -O3'
cmake -DCMAKE_INSTALL_PREFIX=$HOME/usr ..
....

The CMake script provide parameters to control debug, log facility and
optimization.

.Table CMake Command line parameters (cmake -DWITH_LOG=OFF ...)
[cols="1,1,5a", options="header"]
|===
|name| default| summary

| WITH_LOG
| ON
| Enable log message on standard output.

| WITH_DEBUG
| ON
| Enable maximum debug function and add more log message. Be careful, this mode slow down computation.

| WITH_FULL_OPTIMIZATION
| OFF
| Enable optimal computation but remove some control on float and control.
|===

=== Update installation

First, we need to update the Git repository with the following
commands:

....
cd baryonyx
git pull -r
git submodule update --recursive
....

Then go to the build directory and restart compilation and
installation :

....
cd baryonyx
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make install
....

== Usage

=== Solver & Optimizer

To run Baryonyx in solver mode (i.e. trying to valid all constraints):

....
baryonyx-0.5 file.lp
....

To run baryonyx into the heuristic model (i.e. trying to valid all
constraints and optimize the solution), add a `-o` or `--optimize`
option to the command line:

....
baryonyx-0.5 -o file.lp
....

To run baryonyx into the heuristic model (i.e. trying to valid all
constraints and optimize the solution), add a `-o` or `--optimize`
option to the command line:

....
baryonyx-0.5 -o file.lp
....

The Baryonyx solver have many parameters. Some parameters are global,
some specific for the optimization algorithms.

.Table Command line global parameters
[cols="1,1,5a", options="header"]
|===
|name| type| summary

| --help -h
|
| Show help message

| --quiet -q
|
| Remove many console output

| --bench [name]
|
| Start benchmark. Need csv input files

| --optimize -O
|
| Start Baryonyx in optimization mode, default is to use the solve mode

| --limit -l -plimit
| integer
| number of loop to stop algorithm

| --verbose -v
| integer
| verbose level from 0 (very very verbose in debug mode) to 7 (quiet)

| --disable-preprocessing -np
|
| disable the use of preprocessing

| --random
|
| use the pure random solver (for benchmark) instead of the Bastert/Wedelin algorithm.

| --auto[:= ]value
| string
| Select the type of optimizer meta-heuristic. Values are:

* `none` without specific algorithm.
* `manual` tries to update parameters to found best solution.
* `nlopt` tries to update parameters to found best solution using nlopt library and the Nelder Mead algorithm.
* `branch` split recursively original problem to found best solution.
* `branch-manual` mix branch and manual algorithm.
* `branch-nlopt` mix branch and nlopt algorithm.

|===

To assign parameters to solver or optimizer algorithms, use the `-p
[name]:value` syntax in the command line:

.Table Command line parameters
[cols="1,1,5a", options="header"]
|===
|name| type| summary

| time-limit
| real
| time in second to stop algorithm or stop the optimize mode

| limit
| integer
| number of loop to stop algorithm

| w
| double
| warmup-iterator [0, 1] A percentage of `limit` loop and if w is greater than 1, the number of loop without updating kappa

| theta
| real
| history parameters [0, 1[

| delta
| real
| influence parameters [0, +oo[

| kappa-min
| real
| kappa minimal value  [0, kappa-max

| kappa-step
| real
| kappa updater [0, +oo[

| kappa-max
| real
| kappa maximal value ]kappa-min, +oo[ to stop algorithm

| alpha
| real
| adaptiveness parameter

| pushing-k-factor
| integer
| use to lower the kappa using the push system

| pushes-limit
| integer
| number of push before stopping the algorithm

| pushing-objective-amplifier
| real
| use to make r more similar to costs

| pushing-iteration-limit
| integer
| number of loop before trying a new push

| norm
| string
| Select the cost normalization function

* `none`  let unmodified costs
* `l1` use the l1-norm function
* `l2` use the l2-norm function
* `random` try to avoid equal cost
* `inf` (default): use the infinity norm

| constraint-order
| string
| Remaining constraints order. Values are:

* `none` (default): use the lp format constraint order
* `reversing`: reverse the lp format constraint order
* `random-sorting`: random the remaining constraint list
* `infeasibility-decr`: compute infeasibility constraint in decremental order
* `infeasibility-incr`: compute infeasibility constraint in incremental order
* `lagrangian-decr`: sort violated constraints according to the Lagrangian multiplier values in decremental order
* `lagrangian-incr`: sort violated constraints according to the Lagrangian multiplier values in incremental order
* `pi-sign-change`: random the remaining constraint list if the lagrangian multipliers signs have changed
* `cycle`: switch the constraint order after each `update_row`. Starts from `none` to `pi-sign-change`.

| preprocessing
| string
| Constraints matrix A order. Values are:

* `none`: Use the raw_problem (or lp file) order for constraints and variables.
* `memory`: Default, use the raw_problem (or lp file) order for constraints but sort the variables to improve the memory cache efficiency.
* `less_greater_equal`: sort constraints according to their type (first less and finally greater then equal) and sort variable to improve the memory cache efficiency.
* `less_equal_greater`: sort constraints according to their type (first less
  and finally equal then greater) and sort variable to improve the memory cache
  efficiency.
* `greater_less_equal`: sort constraints according to their type (first greater
  then less and finally equal) and sort variable to improve the memory cache
  efficiency.
* `greater_equal_less`: sort constraints according to their type (first greater
  then equal and finally less) and sort variable to improve the memory cache
  efficiency.
* `equal_less_greater`: sort constraints according to their type (first equal
  then less and finally greater) and sort variable to improve the memory cache
  efficiency.
* `equal_greater_less`: sort constraints according to their type (first equal
  then greater and finally less) and sort variable to improve the memory cache
  efficiency.
* `p1`: reserved
* `p2`: reserved
* `p3`: reserved
* `p4`: reserved

| observation
| string
| Select the type of observation mechanism (only in solve mode)

* `none` no observation (default).
* `pnm` produce picture files for the P matrix (one per loop) and Pi vector (Lagrangian multipliers) each loop
* `file` produce CSV files for the P matrix (one per loop) and Pi vector (Lagrangian multipliers) each loop

| floating-point_type
| string
| Select the type of real use internally in the solvers. Values are:

* `float` float (32 bits)
* `double` double (64 bits)
* `longdouble` long double (84 or 128 bits)

| print-level
| integer
| show information if greater than 0

| init-policy (solver only)
| string
| Change the initialization and reinitialization policy of the solution vector. Values are:

* `bastert`: for each variable (or at `init-policy-random` rate) use cost
  values to set or unset variable.
* `pessimistic-solve`: found a solution for each (or at `init-policy-random`
  rate) constraints. For soft constraints, affect one to strict minimum
  variables.
* `optimistic-solve`: found a solution for each (or or `init-policy-random`
  rate) constraints. For soft constraints, affect one to the maximum variables
  that valid the constraint.

| init-policy-random (solver only)
| real
| [0-1] (default, 0.5) parameter of the bernoulli's law to be used in
  conjunction with the `init-policy` parameter. If the law returns 1, it
  uses the `init-policy` algorithm to initialize `X_i`, 0 means use a toss
  up to choose 0 or 1 according to the `init-random` value.

| init-crossover-bastert-insertion (optimizer only)
| real
| [0-1] Probability to insert a bastert solution during the crossover
  operation.

| init-crossover-solution-selection-mean (optimizer only)
| real
| [0-1] Probability to select a solution to do the crossover operation. This
  parameter allows the selection of solution in the population. 0 means best
  solution, 1 means the worst in mean.

| init-crossover-solution-selection-stddev (optimizer only)
| real
| [0-1] Probability to select a solution to do the crossover operation. This
  parameter allows the selection of solution in the population. The standard
  deviation for the normal probability law.

| init-mutation-variable-mean (optimizer only)
| real
| [0-1] Probability to mutate the solution after the crossover operation. This
  parameter defines the number of variables to change. The mean for the normal
  probability law.

| init-mutation-variable-stddev (optimizer only)
| real
| [0-1] Probability to mutate the solution after the crossover operation. This
  parameter defines the number of variables to change. The standard deviatation
  for the normal probability law.

| init-mutation-value-mean (optimizer only)
| real
| [0-1] Probability to mutate the solution after the crossover operation. This
  parameter defines the value of the variable. The mean for the normal
  probability law.

| init-mutation-value-stddev (optimizer only)
| real
| [0-1] Probability to mutate the solution after the crossover operation. This
  parameter defines the value of the variable. The standard deviation for the
  normal probability law.

| storage-type
| string
| Change the solution storage policy for the optimizer mode.

* `one` (default): stores only the best solution found.
* `bound`: stores the best and the bad solution found.
* `five`: stores the best five solution found.

|===

For example:

....
baryonyx -p limit:1000000 lib/test/prevl1.lp
baryonyx -p limit:-1 -p kappa-min:0.2 lib/test/prevl1.lp
....

=== Benchmark

Baryonyx permits to run benchmark on a set of problems described in a `csv`
files. This option is available using the `--bench [name]` option and `csv`
files. All Baryonyx parameters are available to perform the benchmark.

For example:

....
baryonyx --bench bx-0.5 -pdelta:0.01 -ptime-limit:60 spp.csv
....

The benchmark mode updates the `csv` file with results of computation. The
`csv` format is:

....
file optimum status cplex lsp bx-0.2 <1>
cplex:
lsp:    <2>
bx-0.2:
scp410 optimum 514 514 514 804 <3>
scp41 optimum 429 429 429 627
scp42 optimum 512 512 512 934
....

<1> The header: three columns mandatory (`file`, `optimum`, `status`) and one
solver per column. In this example, cplex, local solver and baryonyx 0.2.
<2> The description part: one line per solver to describe version and parameter
for example.
<3> Finally, one line per solve: model name (with or without extension), status
(optimum/feasible), best solution found and solver's solution. `inf` can be use
to indicate no solution found.

In benchmark directory, some files are provided and a script to download
classical problem.

== R

To use rbaryonyx, you must compile and install the baryonyx library.
Follow the previous section and install R.

=== Installation

The R rbaryonyx package requires several packages. Then, under a R terminal:

....
cd baryonyx/rbaryonyx
R CMD REMOVE rbaryonyx <1>

install.packages("roxygen2") <2>
install.packages("Rcpp")
install.packages("devtools")

library(Rcpp) <3>
compileAttributes(".")
library(devtools)
devtools::document()
devtools::build()
devtools::install()

library(rbaryonyx) <4>
?rbaryonyx <5>
....

<1> Remove previous installed version of rbaryonyx
<2> Install the dependencies of rbaryonyx
<3> Build the rbaryonyx package
<4> Load the package
<5> The help

=== API

Two functions are provided to solve or optimize 01 linear programming
problem. Parameters are the same as `C++ API`. These function returns a
scalar:

* If a solution is found:
** if the problem is a minimization: the value of the solution found.
** if the problem is a maximization: the inverse of the solution found.
* If no solution is found, we use the limits of the objective function (minimal
  and maximal value possible.
** if the problem is a minimization: the maximal value possible + the remaining
   constraints.
** if the problem is a maximization: the inverse of the minimal value possible
   + the remaining constraints.
* If a error occurred (not enough memory, problem error etc.):
** if the problem is a minimization: the maximal value possible + the number of
   constraints .
** if the problem is a maximization: the inverse of the minimal value possible
   + the number of constraints.

[source,R]
----
solve_01lp_problem <- function(file_path, limit = 1000L, theta = 0.5,
  delta = 1e-4, constraint_order = 0L, kappa_min = 0.1, kappa_step = 1e-4,
  kappa_max = 1.0, alpha = 1.0, w = 500L, time_limit = 10.0, seed = -1L,
  thread = 1L, norm = 4L, pushing_k_factor = 0.9,
  pushing_objective_amplifier = 5.0, pushes_limit = 10L,
  pushing_iteration_limit = 20L, init_policy = 0L, init_random = 0.5,
  float_type = 1L, verbose = TRUE)

optimize_01lp_problem <- function(file_path, limit = 1000L, theta = 0.5,
  delta = 1e-4, constraint_order = 0L, kappa_min = 0.1, kappa_step = 1e-4,
  kappa_max = 1.0, alpha = 1.0, w = 500L, time_limit = 10.0, seed = -1L,
  thread = 1L, norm = 4L, pushing_k_factor = 0.9,
  pushing_objective_amplifier = 5.0, pushes_limit = 10L,
  pushing_iteration_limit = 20L, init_policy = 0L, init_random = 0.5,
  float_type = 1L, verbose = TRUE)
----

=== Usage

Apply morris method to found useful parameters:

[source,R]
----
library(rbaryonyx)
library(sensitivity)

factors = c("theta", "delta", "constraint_order", "kappa_min", "kappa_step",
  "kappa_max", "alpha", "w", "norm", "pushing_k_factor",
  "pushing_objective_amplifier", "pushes_limit", "pushing_iteration_limit",
  "float_type")

bounds = data.frame(
  min=c(
    0,     # theta
    0,     # delta
    0,     # constraint_order
    0,     # kappa_min
    1e-16, # kappa_step
    1.0,   # kappa_max
    0.0,   # alpha
    50,    # w
    0,     # norm
    0.1,   # pushing_k_factor
    1.0,   # pushing_objective_amplifier
    10,    # pushes_limit
    20,    # pushing_iteration_limit
    0,     # init_policy
    0.0,   # init_random
    0
    ),    # float_type
max=c(
    1,     # theta
    0,     # delta
    4,     # constraint_order
    0.1,   # kappa_min
    1e-1,  # kappa_step
    1.0,   # kappa_max
    2.0,   # alpha
    500,   # w
    4,     # norm
    1,     # pushing_k_factor
    10.0,  # pushing_objective_amplifier
    100,   # pushes_limit
    200,   # pushing_iteration_limit
    2,     # init_policy
    1.0,   # init_random
    2))    # float_type

rownames(bounds) <- factors

morrisDesign <- morris(model = NULL,
                factors = factors,
                r = 10,
                design=list(type="oat", levels=10, grid.jump=5),
                binf = bounds$min,
                bsup = bounds$max,
                scale=TRUE)

solve_lp <- function(x, file_path, limit=10000, time_limit=10, seed=123456789, thread=1) {
  r <- rbaryonyx::solve_01lp_problem(file_path = file_path,
                   limit = limit,
                   theta = x["theta"],
                   delta = x["delta"],
                   constraint_order = x["constraint_order"],
                   kappa_min = x["kappa_min"],
                   kappa_step = x["kappa_step"],
                   kappa_max = x["kappa_max"],
                   alpha = x["alpha"],
                   w = x["w"],
                   time_limit = time_limit,
                   seed = seed,
                   thread = thread,
                   norm = x["norm"],
                   pushing_k_factor = x["pushing_k_factor"],
                   pushing_objective_amplifier = x["pushing_objective_amplifier,"],
                   pushes_limit = x["pushes_limit"],
                   pushing_iteration_limit = x["pushing_iteration_limit"],
                   init_policy = x["init_policy"],
                   init_random = x["init_random"],
                   float_type = x["float_type"])

  return(r)
}

r = apply(morrisDesign$X, 1, solve_lp, file_path="verger_5_5.lp", thread=1, limit=10000, time_limit=10, seed=123456789)

morrisDesign$Y <- r
mu <- apply(morrisDesign$X,2,mean)
mu.star <- apply(morrisDesign$X, 2, function(x) mean(abs(x)))
sigma <- apply(morrisDesign$ee, 2, sd)

apply(morrisDesign$X, 2, function(v) plot(factor(v), r))
----

Use RGenoud method to found best paramter values:

[source,R]
----
library(rgenoud)
library(rbaryonyx)
library(parallel)

optim_gen_lp <- function(x) {
  r <- rbaryonyx::optimize_01lp_problem(
           file_path = "rail507pre.lp",
           limit = -1,
           theta = x[1],
           delta = x[2],
           constraint_order = 0,
           kappa_min = x[3],
           kappa_step = x[4],
           kappa_max = 1.0,
           alpha = 1.0,
           w = 60,
           time_limit = 10,
           seed = 123654785,
           thread = 4,
           norm = 0,
           pushing_k_factor = 1,
           pushing_objective_amplifier = 10,
           pushes_limit = 20,
           pushing_iteration_limit = 50,
           init_policy = 0,
           init_random = 0.5,
           float_type = 1,
           verbose = FALSE)

  return(r)
}

d = matrix(c(0.0, 0.00001, 0.0, 1e-10,
             1.0, 0.001,   0.2, 1e-4),
             nrow=4, ncol=2)

s = c(0.5, 0.003226, 0.1, 1e-8)

no_cores <- detectCores() - 1
cl <- makeCluster(no_cores, outfile="debug.txt")

claw1 <- genoud(optim_gen_lp, nvars=4,
                Domains=d,
                starting.values=s,
                cluster=cl,
                boundary.enforcement=1,
                max=FALSE, pop.size=10)
----

=== Upgrade

To upgrade to the latest version of rbaryonyx, under bash (or
equivalent):

[source,bash]
----
cd baryonyx
git pull -r <1>
cd build
make -j4 <2>
make install
R CMD REMOVE rbaryonyx <3>
cd rbaryonyx
Rscript -e 'library(Rcpp); compileAttributes(".")'
Rscript -e 'library(devtools); devtools::document()'
cd ..
R CMD build rbaryonyx <4>
R CMD INSTALL rbaryonyx_1.0.tar.gz
----

<1> Update the baryonyx and rbaryonyx from Git
<2> Build and install baryonyx
<3> Remove old rbaryonyx package
<4> Build and install

= Baryonyx
Gauthier Quesnel <gauthier.quesnel@inra.fr>
v0.5.x, 2019-??-??
:toc:
:homepage: https://github.com/quesnel/baryonyx/

https://en.wikipedia.org/wiki/Baryonyx[Baryonyx] is an integer and binary linear
programming solver based on the http://www.cse.chalmers.se/~dag/[Dag Wedelin]
heuristic.

[width="15%"]
|============
| https://travis-ci.org/quesnel/baryonyx[image:https://travis-ci.org/quesnel/baryonyx.png?branch=master[Build Status]] | https://ci.appveyor.com/project/quesnel/baryonyx?branch=master[image:https://ci.appveyor.com/api/projects/status/github/quesnel/baryonyx?branch=master&svg=true[Build Status]]
|============

Copyright © 2017-2019 http://www.inra.fr/en[INRA]

The software is released under the MIT license. See the LICENSE file.

== Baryonyx

=== Requirements and recommended

* `cmake` (≥ 3.11)
* $$C++$$ compiler with $$C++17$$ support:
** `gcc` ≥ 7 (https://www.gnu.org/software/gcc/projects/cxx-status.html[notes])
** `clang` ≥ 5 (https://clang.llvm.org/cxx_status.html[notes])
** `visual studio 2017 15.9` with the latest patchs of 2018 (https://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2017-relnotes[notes])

For recent Debian GNU/Linux and Ubuntu derivatives (remove clang to
only use gcc):

[source,bash]
....
apt-get install build-essential cmake clang
....

For Windows, install the https://www.cmake.org[CMake program] and
Visual Studio 2017 (MSVC). You may also install the vcpkg program to
install nlopt and other dependencies.

* `nlopt` library - optimization library to automatic parametrization
 of the Baryonyx solver parameters.

=== First installation

First, we clone Baryonyx git repository and the submodule.

....
git clone https://github.com/quesnel/baryonyx.git
cd baryonyx
git submodule update --init --recursive
....

Default, Baryonyx provides a shared library `libbaryonyx-0.4.so` (with
hidden symbol), a static library `libbaryonyx-0.4.a` (all symbols are
public) and an executable `baryonyx-0.4`. To compile and install in
the default CMake install directory:

....
cd baryonyx
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make install
....

Previous command line install Baryonyx program and library into the
`/usr/local` prefix. If you install into another directory, you need
to define three environment variables (into your `.bashrc` or
equivalent). If you install into `$HOME/usr` for example, you need to
define in your `.bashrc`:

....
export PATH=$PATH:$HOME/usr/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/usr/lib
export PKG_CONFIG_PATH=$PKG_CONFIX_PATH:$HOME/usr/lib/pkgconfig
....

Then run the following commands:

....
cd baryonyx
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/usr ..
make install
....

To override the default build flags, remove the `CMAKE_BUILD_TYPE`
parameter and override the `CXXFLAGS` as follow:

....
export CXX=g++-8
export CXXFLAGS='-Wall -Wextra -Werror -ftree-vectorize -mmmx -msse -msse2 -msse3 -O3'
cmake -DCMAKE_INSTALL_PREFIX=$HOME/usr ..
....

The CMake script provide parameters to control debug, log facility and
optimization.

.Table CMake Command line parameters (cmake -DWITH_LOG=OFF ...)
[cols="1,1,5a", options="header"]
|===
|name| default| summary

| WITH_LOG
| ON
| Enable log message on standard output.

| WITH_DEBUG
| ON
| Enable maximum debug function and add more log message. Be careful, this mode slow down computation.

| WITH_FULL_OPTIMIZATION
| OFF
| Enable optimal computation but remove some control on float and control.
|===

=== Update installation

First, we need to update the Git repository with the following
commands:

....
cd baryonyx
git pull -r
git submodule update --recursive
....

Then go to the build directory and restart compilation and
installation :

....
cd baryonyx
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make install
....

== Usage

=== Solver & Optimizer

To run Baryonyx in solver mode (i.e. trying to valid all constraints):

....
baryonyx-0.4 file.lp
....

To run baryonyx into the heuristic model (i.e. trying to valid all
constraints and optimize the solution), add a `-o` or `--optimize`
option to the command line:

....
baryonyx-0.4 -o file.lp
....

To run baryonyx into the heuristic model (i.e. trying to valid all
constraints and optimize the solution), add a `-o` or `--optimize`
option to the command line:

....
baryonyx-0.4 -o file.lp
....

The Baryonyx solver have many parameters. Some parameters are global,
some specific for the optimization algorithms.

.Table Command line global parameters
[cols="1,1,5a", options="header"]
|===
|name| type| summary

| --help -h
|
| Show help message

| --quiet -q
|
| Remove many console output

| --bench [name]
|
| Start benchmark. Need csv input files

| --optimize -O
|
| Start Baryonyx in optimization mode, default is to use the solve mode

| --limit -l -plimit
| integer
| number of loop to stop algorithm

| --verbose -v
| integer
| verbose level from 0 (very very verbose in debug mode) to 7 (quiet)

| --disable-preprocessing -np
|
| disable the use of preprocessing

| --random
|
| use the pure random solver (for benchmark) instead of the Bastert/Wedelin algorithm.

| --auto[:= ]value
| string
| Select the type of optimizer meta-heuristic. Values are:

* `none` without specific algorithm.
* `manual` tries to update parameters to found best solution.
* `nlopt` tries to update parameters to found best solution using nlopt library and the Nelder Mead algorithm.
* `branch` split recursively original problem to found best solution.
* `branch-manual` mix branch and manual algorithm.
* `branch-nlopt` mix branch and nlopt algorithm.

|===

To assign parameters to solver or optimizer algorithms, use the `-p
[name]:value` syntax in the command line:

.Table Command line parameters
[cols="1,1,5a", options="header"]
|===
|name| type| summary

| time-limit
| real
| time in second to stop algorithm or stop the optimize mode

| limit
| integer
| number of loop to stop algorithm

| w
| double
| warmup-iterator [0, 1] A percentage of `limit` loop and if w is greater than 1, the number of loop without updating kappa

| theta
| real
| history parameters [0, 1[

| delta
| real
| influence parameters [0, +oo[

| kappa-min
| real
| kappa minimal value  [0, kappa-max

| kappa-step
| real
| kappa updater [0, +oo[

| kappa-max
| real
| kappa maximal value ]kappa-min, +oo[ to stop algorithm

| alpha
| real
| adaptiveness parameter

| pushing-k-factor
| integer
| use to lower the kappa using the push system

| pushes-limit
| integer
| number of push before stopping the algorithm

| pushing-objective-amplifier
| real
| use to make r more similar to costs

| pushing-iteration-limit
| integer
| number of loop before trying a new push

| norm
| string
| Select the cost normalization function

* `none`  let unmodified costs
* `l1` use the l1-norm function
* `l2` use the l2-norm function
* `random` try to avoid equal cost
* `inf` (default): use the infinity norm

| constraint-order
| string
| Remaining constraints order. Values are:

* `none` (default): use the lp format constraint order
* `reversing`: reverse the lp format constraint order
* `random-sorting`: random the remaining constraint list
* `infeasibility-decr`: compute infeasibility constraint in decremental order
* `infeasibility-incr`: compute infeasibility constraint in incremental order
* `lagrangian-decr`: sort violated constraints according to the Lagrangian multiplier values in decremental order
* `lagrangian-incr`: sort violated constraints according to the Lagrangian multiplier values in incremental order
* `pi-sign-change`: random the remaining constraint list if the lagrangian multipliers signs have changed
* `cycle`: switch the constraint order after each `update_row`. Starts from `none` to `pi-sign-change`.

| preprocessing
| string
| Constraints matrix A order. Values are:

* `none`: Use the raw_problem (or lp file) order for constraints and variables.
* `memory`: Default, use the raw_problem (or lp file) order for constraints but sort the variables to improve the memory cache efficiency.
* `less_greater_equal`: sort constraints according to their type (first less and finally greater then equal) and sort variable to improve the memory cache efficiency.
* `less_equal_greater`: sort constraints according to their type (first less
  and finally equal then greater) and sort variable to improve the memory cache
  efficiency.
* `greater_less_equal`: sort constraints according to their type (first greater
  then less and finally equal) and sort variable to improve the memory cache
  efficiency.
* `greater_equal_less`: sort constraints according to their type (first greater
  then equal and finally less) and sort variable to improve the memory cache
  efficiency.
* `equal_less_greater`: sort constraints according to their type (first equal
  then less and finally greater) and sort variable to improve the memory cache
  efficiency.
* `equal_greater_less`: sort constraints according to their type (first equal
  then greater and finally less) and sort variable to improve the memory cache
  efficiency.
* `p1`: reserved
* `p2`: reserved
* `p3`: reserved
* `p4`: reserved

| observation
| string
| Select the type of observation mechanism (only in solve mode)

* `none` no observation (default).
* `pnm` produce picture files for the P matrix (one per loop) and Pi vector (Lagrangian multipliers) each loop
* `file` produce CSV files for the P matrix (one per loop) and Pi vector (Lagrangian multipliers) each loop

| floating-point_type
| string
| Select the type of real use internally in the solvers. Values are:

* `float` float (32 bits)
* `double` double (64 bits)
* `longdouble` long double (84 or 128 bits)

| print-level
| integer
| show information if greater than 0

| init-policy
| string
| Change the initialization and reinitialization policy of the solution vector. Values are:

* `bastert`: for each variable (or at `init-policy-random` rate) use cost
  values to set or unset variable.
* `pessimistic-solve`: found a solution for each (or at `init-policy-random`
  rate) constraints. For soft constraints, affect one to strict minimum
  variables.
* `optimistic-solve`: found a solution for each (or or `init-policy-random`
  rate) constraints. For soft constraints, affect one to the maximum variables
  that valid the constraint.
* `cycle` (default): Only for the optimization mode, start with the
  `pessimistic-solve` mode and change to `bastert` then `pessimistic-solve`
  mode. The change between mode is done if and only if three times,
  optimization fails to improve the current best solution.

| init-policy-random
| real
| [0-1] (default, 0.5) parameter of the bernoulli's law to be used in conjunction with the `init-policy` parameter. If the law returns 1, it uses the `init-policy` algorithm to initialize `X_i`, 0 means use a toss up to choose 0 or 1 according to the `init-random` value.

| init-random
| real
| [0-1] (default, 0.5) parameter _p_ of the bernoulli's law used when 0 occurs with the `init-policy-random`.

| storage-type
| string
| Change the solution storage policy for the optimizer mode.

* `one` (default): stores only the best solution found.
* `bound`: stores the best and the bad solution found.
* `five`: stores the best five solution found.

|===

For example:

....
baryonyx -p limit:1000000 lib/test/prevl1.lp
baryonyx -p limit:-1 -p kappa-min:0.2 lib/test/prevl1.lp
....

=== Benchmark

Baryonyx permits to run benchmark on a set of problems described in a `csv`
files. This option is available using the `--bench [name]` option and `csv`
files. All Baryonyx parameters are available to perform the benchmark.

For example:

....
baryonyx --bench bx-0.4 -pdelta:0.01 -ptime-limit:60 spp.csv
....

The benchmark mode updates the `csv` file with results of computation. The
`csv` format is:

....
file optimum status cplex lsp bx-0.2 <1>
cplex:
lsp:    <2>
bx-0.2:
scp410 optimum 514 514 514 804 <3>
scp41 optimum 429 429 429 627
scp42 optimum 512 512 512 934
....

<1> The header: three columns mandatory (`file`, `optimum`, `status`) and one
solver per column. In this example, cplex, local solver and baryonyx 0.2.
<2> The description part: one line per solver to describe version and parameter
for example.
<3> Finally, one line per solve: model name (with or without extension), status
(optimum/feasible), best solution found and solver's solution. `inf` can be use
to indicate no solution found.

In benchmark directory, some files are provided and a script to download
classical problem.

== R

To use rbaryonyx, you must compile and install the baryonyx library.
Follow the previous section and install R.

=== Installation

The R rbaryonyx package requires several packages. Then, under a R terminal:

....
cd baryonyx/rbaryonyx
R CMD REMOVE rbaryonyx <1>

install.packages("roxygen2") <2>
install.packages("Rcpp")
install.packages("devtools")

library(Rcpp) <3>
compileAttributes(".")
library(devtools)
devtools::document()
devtools::build()
devtools::install()

library(rbaryonyx) <4>
?rbaryonyx <5>
....

<1> Remove previous installed version of rbaryonyx
<2> Install the dependencies of rbaryonyx
<3> Build the rbaryonyx package
<4> Load the package
<5> The help

=== API

Two functions are provided to solve or optimize 01 linear programming
problem. Parameters are the same as `C++ API`. These function returns a
scalar:

* If a solution is found:
** if the problem is a minimization: the value of the solution found.
** if the problem is a maximization: the inverse of the solution found.
* If no solution is found, we use the limits of the objective function (minimal
  and maximal value possible.
** if the problem is a minimization: the maximal value possible + the remaining
   constraints.
** if the problem is a maximization: the inverse of the minimal value possible
   + the remaining constraints.
* If a error occurred (not enough memory, problem error etc.):
** if the problem is a minimization: the maximal value possible + the number of
   constraints .
** if the problem is a maximization: the inverse of the minimal value possible
   + the number of constraints.

[source,R]
----
solve_01lp_problem <- function(file_path, limit = 1000L, theta = 0.5,
  delta = 1e-4, constraint_order = 0L, kappa_min = 0.1, kappa_step = 1e-4,
  kappa_max = 1.0, alpha = 1.0, w = 500L, time_limit = 10.0, seed = -1L,
  thread = 1L, norm = 4L, pushing_k_factor = 0.9,
  pushing_objective_amplifier = 5.0, pushes_limit = 10L,
  pushing_iteration_limit = 20L, init_policy = 0L, init_random = 0.5,
  float_type = 1L, verbose = TRUE)

optimize_01lp_problem <- function(file_path, limit = 1000L, theta = 0.5,
  delta = 1e-4, constraint_order = 0L, kappa_min = 0.1, kappa_step = 1e-4,
  kappa_max = 1.0, alpha = 1.0, w = 500L, time_limit = 10.0, seed = -1L,
  thread = 1L, norm = 4L, pushing_k_factor = 0.9,
  pushing_objective_amplifier = 5.0, pushes_limit = 10L,
  pushing_iteration_limit = 20L, init_policy = 0L, init_random = 0.5,
  float_type = 1L, verbose = TRUE)
----

=== Usage

Apply morris method to found useful parameters:

[source,R]
----
library(rbaryonyx)
library(sensitivity)

factors = c("theta", "delta", "constraint_order", "kappa_min", "kappa_step",
  "kappa_max", "alpha", "w", "norm", "pushing_k_factor",
  "pushing_objective_amplifier", "pushes_limit", "pushing_iteration_limit",
  "float_type")

bounds = data.frame(
  min=c(
    0,     # theta
    0,     # delta
    0,     # constraint_order
    0,     # kappa_min
    1e-16, # kappa_step
    1.0,   # kappa_max
    0.0,   # alpha
    50,    # w
    0,     # norm
    0.1,   # pushing_k_factor
    1.0,   # pushing_objective_amplifier
    10,    # pushes_limit
    20,    # pushing_iteration_limit
    0,     # init_policy
    0.0,   # init_random
    0
    ),    # float_type
max=c(
    1,     # theta
    0,     # delta
    4,     # constraint_order
    0.1,   # kappa_min
    1e-1,  # kappa_step
    1.0,   # kappa_max
    2.0,   # alpha
    500,   # w
    4,     # norm
    1,     # pushing_k_factor
    10.0,  # pushing_objective_amplifier
    100,   # pushes_limit
    200,   # pushing_iteration_limit
    2,     # init_policy
    1.0,   # init_random
    2))    # float_type

rownames(bounds) <- factors

morrisDesign <- morris(model = NULL,
                factors = factors,
                r = 10,
                design=list(type="oat", levels=10, grid.jump=5),
                binf = bounds$min,
                bsup = bounds$max,
                scale=TRUE)

solve_lp <- function(x, file_path, limit=10000, time_limit=10, seed=123456789, thread=1) {
  r <- rbaryonyx::solve_01lp_problem(file_path = file_path,
                   limit = limit,
                   theta = x["theta"],
                   delta = x["delta"],
                   constraint_order = x["constraint_order"],
                   kappa_min = x["kappa_min"],
                   kappa_step = x["kappa_step"],
                   kappa_max = x["kappa_max"],
                   alpha = x["alpha"],
                   w = x["w"],
                   time_limit = time_limit,
                   seed = seed,
                   thread = thread,
                   norm = x["norm"],
                   pushing_k_factor = x["pushing_k_factor"],
                   pushing_objective_amplifier = x["pushing_objective_amplifier,"],
                   pushes_limit = x["pushes_limit"],
                   pushing_iteration_limit = x["pushing_iteration_limit"],
                   init_policy = x["init_policy"],
                   init_random = x["init_random"],
                   float_type = x["float_type"])

  return(r)
}

r = apply(morrisDesign$X, 1, solve_lp, file_path="verger_5_5.lp", thread=1, limit=10000, time_limit=10, seed=123456789)

morrisDesign$Y <- r
mu <- apply(morrisDesign$X,2,mean)
mu.star <- apply(morrisDesign$X, 2, function(x) mean(abs(x)))
sigma <- apply(morrisDesign$ee, 2, sd)

apply(morrisDesign$X, 2, function(v) plot(factor(v), r))
----

Use RGenoud method to found best paramter values:

[source,R]
----
library(rgenoud)
library(rbaryonyx)
library(parallel)

optim_gen_lp <- function(x) {
  r <- rbaryonyx::optimize_01lp_problem(
           file_path = "rail507pre.lp",
           limit = -1,
           theta = x[1],
           delta = x[2],
           constraint_order = 0,
           kappa_min = x[3],
           kappa_step = x[4],
           kappa_max = 1.0,
           alpha = 1.0,
           w = 60,
           time_limit = 10,
           seed = 123654785,
           thread = 4,
           norm = 0,
           pushing_k_factor = 1,
           pushing_objective_amplifier = 10,
           pushes_limit = 20,
           pushing_iteration_limit = 50,
           init_policy = 0,
           init_random = 0.5,
           float_type = 1,
           verbose = FALSE)

  return(r)
}

d = matrix(c(0.0, 0.00001, 0.0, 1e-10,
             1.0, 0.001,   0.2, 1e-4),
             nrow=4, ncol=2)

s = c(0.5, 0.003226, 0.1, 1e-8)

no_cores <- detectCores() - 1
cl <- makeCluster(no_cores, outfile="debug.txt")

claw1 <- genoud(optim_gen_lp, nvars=4,
                Domains=d,
                starting.values=s,
                cluster=cl,
                boundary.enforcement=1,
                max=FALSE, pop.size=10)
----

=== Upgrade

To upgrade to the latest version of rbaryonyx, under bash (or
equivalent):

[source,bash]
----
cd baryonyx
git pull -r <1>
cd build
make -j4 <2>
make install
R CMD REMOVE rbaryonyx <3>
cd rbaryonyx
Rscript -e 'library(Rcpp); compileAttributes(".")'
Rscript -e 'library(devtools); devtools::document()'
cd ..
R CMD build rbaryonyx <4>
R CMD INSTALL rbaryonyx_1.0.tar.gz
----

<1> Update the baryonyx and rbaryonyx from Git
<2> Build and install baryonyx
<3> Remove old rbaryonyx package
<4> Build and install


Use Markdown compatible syntax

Use Markdown compatible syntax

= Asciidoctor.js CLI

ifdef::env-github[]
image:https://img.shields.io/travis/asciidoctor/asciidoctor-cli.js/master.svg[Travis build status, link=https://travis-ci.org/asciidoctor/asciidoctor-cli.js]
image:https://img.shields.io/npm/v/@asciidoctor/cli.svg[npm version, link=https://www.npmjs.org/package/@asciidoctor/cli]
endif::[]

The Command Line Interface (CLI) for Asciidoctor.js.

Install Asciidoctor.js globally and you'll have access to the `asciidoctor` command anywhere on your system:

    $ npm i -g asciidoctor

Type `asciidoctor --help` for more information.


Update documentation.

Update documentation.

= Linux System Programming - Rotate by 13 places (ROT13)
A small program that performs rotate by 13 places ``encryption''.

== Compile & Run
[source,bash]
----
$ git clone https://github.com/oneonestar/LSP_ROT13.git
$ cd LSP_ROT13
$ mkdir build
$ cmake ..
$ make
$ ./ROT13
----

== Usage
----
Usage: ROT13 [OPTION...] [FILE...]

ROT13 -- Rotate by 13 places encryption

  -r, --reverse              Reverse shift (right shift)
  -s, --shift=AMOUNT         Shift by this AMOUNT (default 13)
  -v, --verbose              Verbose Mode
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.
----
TIP: If no FILE provided, program will read from standard input.

== Example
[source,bash]
----
$ ./ROT13                       #left shift of 13, reading from stdin
$ ./ROT13 -s 10                 #left shift of 10
$ ./ROT13 -r -s 8               #right shift of 8
$ ./ROT13 Makefile              #encrypt the Makefile, output as Makefile.out
----

== Bugs & Feedback
Report bugs to Star Poon <oneonestar@gmail.com>.

= Linux System Programming - Rotate by 13 places (ROT13)
A small program that performs rotate by 13 places ``encryption''.

== Usage
----
Usage: ROT13 [OPTION...] [FILE...]
ROT13 -- Rotate by 13 places encryption

  -r, --reverse              Reverse shift (right shift).
  -s, --shift=AMOUNT         Shift by this AMOUNT. (default 13)
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

Report bugs to Star Poon <oneonestar@gmail.com>.
----
TIP: If no FILE provided, program will read standard input.

== Compile & Run
[source,bash]
----
$ git clone https://github.com/oneonestar/LSP_ROT13.git
$ cd LSP_ROT13
$ mkdir build
$ cmake ..
$ make
$ ./ROT13


update readme - supported versions

update readme - supported versions

update the wording on the supported versions

== Crunchy PostgreSQL Containers
v1.4.1, {docdate}

image::docs/crunchy_logo.png?raw=true[]

Crunchy Container Suite provides Docker containers that enable
rapid deployment of PostgreSQL, including administration and
monitoring tools. Multiple styles of deploying PostgreSQL clusters
are supported.

The containers will execute in the following environments:

 * Docker 1.12 and above
 * Openshift 3.4 and above
 * Kubernetes 1.5 and above

The project includes the following containers:

 * link:docs/containers.adoc#crunchy-postgres[crunchy-postgres] - executes Postgres
 * link:docs/containers.adoc#crunchy-postgres-gis[crunchy-postgres-gis] - executes Postgres plus the PostGIS extensions
 * link:docs/containers.adoc#crunchy-backup[crunchy-backup] - performs a full database backup
 * link:docs/containers.adoc#crunchy-pgpool[crunchy-pgpool] - executes pgpool
 * link:docs/containers.adoc#crunchy-pgbadger[crunchy-pgbadger] - executes pgbadger
 * link:docs/containers.adoc#crunchy-watch[crunchy-watch] - performs a form of automated failover
 * link:docs/metrics.adoc#crunchy-collect[crunchy-collect] - collects Postgres metrics
 * link:docs/metrics.adoc#crunchy-prometheus[crunchy-prometheus] -stores Postgres metrics
 * link:docs/metrics.adoc#crunchy-grafana[crunchy-grafana] - graphs Postgres metrics
 * link:docs/containers.adoc#crunchy-pgbouncer[crunchy-pgbouncer] - pgbouncer connection pooler and simple form of failover
 * link:docs/containers.adoc#crunchy-pgadmin4[crunchy-pgadmin4] - pgadmin4 web application
 * link:docs/containers.adoc#crunchy-dba[crunchy-dba] - implements a cron scheduler to perform simple DBA tasks
 * link:docs/containers.adoc#crunchy-upgrade[crunchy-upgrade] - allows you to perform a major postgres upgrade using pg_upgrade
 * link:docs/containers.adoc#crunchy-backrest-restore[crunchy-backrest-restore] - allows you to perform a pgbackrest restore

image::docs/containers.png?raw=true[]

For Kubernetes users of these containers, there is an associated
project worth taking a look at that uses the containers found
in this repo and provides a higher level automation.
That project is link:https://github.com/crunchydata/postgres-operator[PostgresOperator]

=== Installation

Complete build and install documentation is found here: link:docs/install.adoc[Install Docs].  The provided Dockerfiles build the containers
on a Centos 7 base image and use the community PostgreSQL RPMs.

Crunchy provides a commercially supported version of these containers
built upon RHEL 7 and the Crunchy supported PostgreSQL.  Contact Crunchy
for more details at http://www.crunchydata.com.

=== Examples

Various examples are provided in link:docs/examples.adoc[the Examples documentation] for running Docker,
Kubernetes, and OpenShift environments.

You will need to set up your environment as per the link:docs/install.adoc[Install documentation] in order to
execute the examples.

== Crunchy PostgreSQL Containers
v1.4.1, {docdate}

image::docs/crunchy_logo.png?raw=true[]

Crunchy Container Suite provides Docker containers that enable
rapid deployment of PostgreSQL, including administration and
monitoring tools. Multiple styles of deploying PostgreSQL clusters
are supported.

The containers will execute in the following environments:

 * Docker 1.12
 * Openshift 3.5
 * Kubernetes 1.6

The project includes the following containers:

 * link:docs/containers.adoc#crunchy-postgres[crunchy-postgres] - executes Postgres
 * link:docs/containers.adoc#crunchy-postgres-gis[crunchy-postgres-gis] - executes Postgres plus the PostGIS extensions
 * link:docs/containers.adoc#crunchy-backup[crunchy-backup] - performs a full database backup
 * link:docs/containers.adoc#crunchy-pgpool[crunchy-pgpool] - executes pgpool
 * link:docs/containers.adoc#crunchy-pgbadger[crunchy-pgbadger] - executes pgbadger
 * link:docs/containers.adoc#crunchy-watch[crunchy-watch] - performs a form of automated failover
 * link:docs/metrics.adoc#crunchy-collect[crunchy-collect] - collects Postgres metrics
 * link:docs/metrics.adoc#crunchy-prometheus[crunchy-prometheus] -stores Postgres metrics
 * link:docs/metrics.adoc#crunchy-grafana[crunchy-grafana] - graphs Postgres metrics
 * link:docs/containers.adoc#crunchy-pgbouncer[crunchy-pgbouncer] - pgbouncer connection pooler and simple form of failover
 * link:docs/containers.adoc#crunchy-pgadmin4[crunchy-pgadmin4] - pgadmin4 web application
 * link:docs/containers.adoc#crunchy-dba[crunchy-dba] - implements a cron scheduler to perform simple DBA tasks
 * link:docs/containers.adoc#crunchy-upgrade[crunchy-upgrade] - allows you to perform a major postgres upgrade using pg_upgrade
 * link:docs/containers.adoc#crunchy-backrest-restore[crunchy-backrest-restore] - allows you to perform a pgbackrest restore

image::docs/containers.png?raw=true[]

For Kubernetes users of these containers, there is an associated
project worth taking a look at that uses the containers found
in this repo and provides a higher level automation.
That project is link:https://github.com/crunchydata/postgres-operator[PostgresOperator]

=== Installation

Complete build and install documentation is found here: link:docs/install.adoc[Install Docs].  The provided Dockerfiles build the containers
on a Centos 7 base image and use the community PostgreSQL RPMs.

Crunchy provides a commercially supported version of these containers
built upon RHEL 7 and the Crunchy supported PostgreSQL.  Contact Crunchy
for more details at http://www.crunchydata.com.

=== Examples

Various examples are provided in link:docs/examples.adoc[the Examples documentation] for running Docker,
Kubernetes, and OpenShift environments.

You will need to set up your environment as per the link:docs/install.adoc[Install documentation] in order to
execute the examples.


Add user guide link

Add user guide link

= flexy-pool
Author <mih_vlad@yahoo.com>
v1.0.0, 2014-02-25

:toc:
:imagesdir: images
:homepage: http://vladmihalcea.com/

== Introduction

The flexy-pool library brings adaptability to a given Connection Pool, allowing it to resize on demand.
This is very handy since most connection pools offer a limited set of dynamic configuration strategies.

== Features

* extensive connection pool support(Bitronix TM, C3PO, DBCP 1, DBCP 2, BoneCP, HikariCP)
* statistics support
** source connection acquiring time histogram
** total connection acquiring time histogram
** retries attempts histogram
** maximum CP size histogram
** connection request count histogram
** connection lease time histogram

https://github.com/vladmihalcea/flexy-pool/wiki/Flexy-Pool-User-Guide[User Guide]

== 1.0 TODO list

* explain all configuration settings
* explain jmx metrics
* add real-life case study

= flexy-pool
Author <mih_vlad@yahoo.com>
v1.0.0, 2014-02-25

:toc:
:imagesdir: images
:homepage: http://vladmihalcea.com/

== Introduction

The flexy-pool library brings adaptability to a given Connection Pool, allowing it to resize on demand.
This is very handy since most connection pools offer a limited set of dynamic configuration strategies.

== Features

* extensive connection pool support(Bitronix TM, C3PO, DBCP 1, DBCP 2, BoneCP, HikariCP)
* statistics support
** source connection acquiring time histogram
** total connection acquiring time histogram
** retries attempts histogram
** maximum CP size histogram
** connection request count histogram
** connection lease time histogram

== 1.0 TODO list

* write installation guide
* write user guide
* explain jmx metrics
* explain all configuration settings
* add real-life case study


Updated README with screenshots.

Updated README with screenshots.

= pcf-environment-performance-test

This is a set of scripts to help you automate performance metrics of your PCF deployment process.

== Install Script

You can simply clone the script to your Mac/Unix/Linux BASH environment, e.g.
----
    git clone https://github.com/nevenc-pivotal/pcf-environment-performance-test.git
    cd pcf-environment-performance-test
----

== Configure Script

In order to make the script work, you need to configure separate directories for each environment, e.g.
----
  emea         ~/.cf-emea
  corp         ~/.cf-corp
  pws          ~/.cf-pws
  myorg        ~/.cf-myorg
  ...
----

You can set an environment by setting `CF_HOME` to specific environment, and setting target and login, repeat for each environment separately, e.g.

----
    export CF_HOME=~/cf-emea
    cf api --skip-ssl-validation https://api.cf.emea.pivotal.io
    cf login
    Email> you@emea.pivotal.io
    Password> **********

    export CF_HOME=~/cf-corp
    cf api --skip-ssl-validation https://api.cf.corp.pivotal.io
    cf login
    Email> you@corp.pivotal.io
    Password> **********

    export CF_HOME=~/cf-pws
    cf api https://api.run.pivotal.io
    cf login
    Email> you@email.com
    Password> **********

    export CF_HOME=~/cf-myorg
    cf api --skip-ssl-validation https://api.cf.myorg.com
    cf login
    Email> you@email.com
    Password> **********

----

== Execute Script

You can execute script by invoking it directly, e.g.

----
./test_performance_deploy.sh

Pushing spring-music to emea
real 78.36
user 1.75
sys 1.70

Removing spring-music from emea
real 9.05
user 0.07
sys 0.02

Pushing spring-music to emea-2015
real 253.44
user 4.80
sys 6.29

Removing spring-music from emea-2015
real 8.28
user 0.07
sys 0.02

Pushing spring-music to pws
real 2.69
user 0.11
sys 0.02

Removing spring-music from pws
real 0.59
user 0.10
sys 0.02

----

You can invoke test script multiple times by invoking the script runner with a number parameter, e.g.

----
./run_test_x_times.sh 2

run: 1

Pushing spring-music to emea
real 78.36
user 1.75
sys 1.70

Removing spring-music from emea
real 9.05
user 0.07
sys 0.02

Pushing spring-music to emea-2015
real 253.44
user 4.80
sys 6.29

Removing spring-music from emea-2015
real 8.28
user 0.07
sys 0.02

Pushing spring-music to pws
real 2.69
user 0.11
sys 0.02

Removing spring-music from pws
real 0.59
user 0.10
sys 0.02

run: 2

Pushing spring-music to emea
real 58.17
user 1.46
sys 1.21

Removing spring-music from emea
real 9.17
user 0.07
sys 0.02

Pushing spring-music to emea-2015
real 236.64
user 4.51
sys 5.86

Removing spring-music from emea-2015
real 8.14
user 0.07
sys 0.02

Pushing spring-music to pws
real 1.85
user 0.12
sys 0.02

Removing spring-music from pws
real 0.57
user 0.11
sys 0.02

----

== Results

You can feed the results into a spreadsheet for nicer presentation, e.g.

![cf push response times](cf_push.png?raw=true "cf push response times")
![cf delete response times](cf_delete.png?raw=true "cf delete response times")

= pcf-environment-performance-test

This is a set of scripts to help you automate performance metrics of your PCF deployment process.

== Install Script

You can simply clone the script to your Mac/Unix/Linux BASH environment, e.g.
----
    git clone https://github.com/nevenc-pivotal/pcf-environment-performance-test.git
    cd pcf-environment-performance-test
----

== Configure Script

In order to make the script work, you need to configure separate directories for each environment, e.g.
----
  emea         ~/.cf-emea
  corp         ~/.cf-corp
  pws          ~/.cf-pws
  myorg        ~/.cf-myorg
  ...
----

You can set an environment by setting `CF_HOME` to specific environment, and setting target and login, repeat for each environment separately, e.g.

----
    export CF_HOME=~/cf-emea
    cf api --skip-ssl-validation https://api.cf.emea.pivotal.io
    cf login
    Email> you@emea.pivotal.io
    Password> **********

    export CF_HOME=~/cf-corp
    cf api --skip-ssl-validation https://api.cf.corp.pivotal.io
    cf login
    Email> you@corp.pivotal.io
    Password> **********

    export CF_HOME=~/cf-pws
    cf api https://api.run.pivotal.io
    cf login
    Email> you@email.com
    Password> **********

    export CF_HOME=~/cf-myorg
    cf api --skip-ssl-validation https://api.cf.myorg.com
    cf login
    Email> you@email.com
    Password> **********
----

== Execute Script

You can execute script by invoking it directly, e.g.

----
./test_performance_deploy.sh

Pushing spring-music to emea
real 78.36
user 1.75
sys 1.70

Removing spring-music from emea
real 9.05
user 0.07
sys 0.02

Pushing spring-music to emea-2015
real 253.44
user 4.80
sys 6.29

Removing spring-music from emea-2015
real 8.28
user 0.07
sys 0.02

Pushing spring-music to pws
real 2.69
user 0.11
sys 0.02

Removing spring-music from pws
real 0.59
user 0.10
sys 0.02

----

You can invoke test script multiple times by invoking the script runner with a number parameter, e.g.

----
./run_test_x_times.sh 2

./run_test_x_times.sh

run: 1

Pushing spring-music to emea
real 78.36
user 1.75
sys 1.70

Removing spring-music from emea
real 9.05
user 0.07
sys 0.02

Pushing spring-music to emea-2015
real 253.44
user 4.80
sys 6.29

Removing spring-music from emea-2015
real 8.28
user 0.07
sys 0.02

Pushing spring-music to pws
real 2.69
user 0.11
sys 0.02

Removing spring-music from pws
real 0.59
user 0.10
sys 0.02

run: 2

Pushing spring-music to emea
real 58.17
user 1.46
sys 1.21

Removing spring-music from emea
real 9.17
user 0.07
sys 0.02

Pushing spring-music to emea-2015
real 236.64
user 4.51
sys 5.86

Removing spring-music from emea-2015
real 8.14
user 0.07
sys 0.02

Pushing spring-music to pws
real 1.85
user 0.12
sys 0.02

Removing spring-music from pws
real 0.57
user 0.11
sys 0.02

----


Doc: README cleanup

Doc: README cleanup

= Language-puppet

A library to work with Puppet manifests, test them and eventually replace everything ruby.

.Basic usage:
```
puppetresources -p /where/your/puppet/files/are -o node.name.com
```

.Easy build instructions:
```
cd language-puppet
cabal update
cabal sandbox init
cabal install -j -p
```

There are also http://lpuppet.banquise.net/download/[binary packages available] .

== Puppetresources

The `puppetresources` command is a command line utility that let you interactively compute catalogs on your local computer. It will then display them on screen, in a nice,
user-friendly colored fashion. It is much faster than its ruby counterpart, and has been designed for giving assistance to the Puppet catalog writer. Here is a list of command line
arguments :

`-p` or `--puppetdir`::

This is the only mandatory argument. It accepts a directory or file path as the argument. In the absence of `-o`, it will parse and display the puppet file given as a parameter.
With `-o` it must point to the base of the puppet directory (the directory that contains the `modules` and `manifests` directories).

`-o` or `--node`::

This let you specify the name of the node you wish to compute the catalog for.
+
If you use `allnodes` as the node name, it will compute the catalogs for all nodes that are specified in `site.pp` (this will not work for regexp-specified or the default nodes). This is useful
for writing automated tests, to check a change didn't break something.
+
If you use `deadcode` as the node name, it will also compute the catalogs for all nodes, but will display the list of puppet files that have not been used, and that might be
deprecated.
+
You might want to run the program with `+RTS -N` with those two modes.

`-t` or `--type`::

Filters the resources of the resulting catalog by type, but specifying a regular expression. Only the resources whose types match the submitted regexp will be displayed.

`-n` or `--name`::

Filters the resources of the resulting catalog by name, but specifying a regular expression. Only the resources whose names match the submitted regexp will be displayed.

`-c` or `--showcontent`::

If `-n` is the exact name of a file type resource defined in the catalog, this will display more nicely display the file content. Useful for debugging templates.
+
Example: `puppetresources -p . -o mynodename -n '/etc/motd' --showcontent`

`--loglevel` or `-v`::

Possible values are : DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY.

`--pdburl`::

Expects the url of a live PuppetDB.

`--pdbfile`::

Expects a path to a *fake* PuppetDB, represented as a YAML file on disk. This option is pretty slow but can be invaluable to test exported resources tricks.

`--hiera`::

Expects the path to the `hiera.yaml` file.

`--ignoremodules`::

Expects a list of comma-separated modules. The interpreter will not try to evaluate the defined types and classes from this module. This is useful for using modules that use bad
practices forbidden by `puppetresources`.

`--nousergrouptest`::

By default, `puppetresources` will check that all users and groups referenced by `cron`, `file`, etc. types are defined somewhere in the catalog (except for a list of widely
available users, such as `root`). This flag disables these tests.

`--commitdb`::

When this flag is set, exported resources, catalogs and facts are saved in the PuppetDB. This is useful in conjunction with `--pdbfile`.

`--checkExported`::

When this flag is set, exported resources are saved in the PuppetDB. This is useful in conjunction with `--pdbfile`.

`-j` or `--JSON`::

Displays the catalog as a Puppet-compatible JSON file, that can then be used with `puppet apply`.

`--facts-override` and `--facts-defaults`::

Both options expect a path to a YAML file defining facts. The first option will override the facts that are collected locally, while the second will merely provide default values
for them.

`--strict`::

Enable strict mode.
The strict mode is less permissive than vanilla Puppet.
It is meant to prevent some pitfalls by enforcing good practices.
For instance it refuses to silently ignore/convert `undef` variables.

== pdbQuery

The `pdbQuery` command is used to work with different implementations of PuppetDB (the official one with its HTTP API, the file-based backend and dummy ones). Its main use is to
export data from production PuppetDB to a file in order to debug some issue with `puppetresources`. Here is a list of command line arguments :

`-l` or `--location`::

The URL of the PuppetDB when working with a remote PuppetDB, a file path when working with the file-based test implementation.

`-t` or `--pdbtype`::

The type of PuppetDB to work with:

* dummy: a dummy PuppetDB.
* remote: a "real" PuppetDB, accessed by its HTTP API.
* test: a file-based backend emulating a PuppetDB.

.Commands
`dumpfacts`::

Dump all facts, and store them in `/tmp/allfacts.yaml`.

`nodes`::

Dump all nodes

`snapshot`::

Create a test DB from the current DB

`addfacts`::

Adds facts to the test DB for the given node name, if they are not already defined.

== Unsupported Puppet idioms or features

puppet functions::
  * the `require` function is not supported (see https://github.com/bartavelle/language-puppet/issues/17[issue #17])
  * the deprecated `import` function is not supported (see https://github.com/bartavelle/language-puppet/issues/82[issue #82])

custom ruby functions::
Currently the only way to support your custom ruby functions is to rewrite them in Lua.

known differences::
Looking up an undef key is silent in Puppet but it is an error with puppetresources.

= Language-puppet

A library to work with Puppet manifests, test them and eventually replace everything ruby.

.Basic usage:
```
puppetresources -p /where/your/puppet/files/are -o node.name.com
```

.Easy build instructions:
```
cd language-puppet
cabal update
cabal sandbox init
cabal install -j -p
```

There are also http://lpuppet.banquise.net/download/[binary packages available] .

== Puppetresources

The `puppetresources` command is a command line utility that let you interactively compute catalogs on your local computer. It will then display them on screen, in a nice,
user-friendly colored fashion. It is much faster than its ruby counterpart, and has been designed for giving assistance to the Puppet catalog writer. Here is a list of command line
arguments :

`-p` or `--puppetdir`::

This is the only mandatory argument. It accepts a directory or file path as the argument. In the absence of `-o`, it will parse and display the puppet file given as a parameter.
With `-o` it must point to the base of the puppet directory (the directory that contains the `modules` and `manifests` directories).

`-o` or `--node`::

This let you specify the name of the node you wish to compute the catalog for.
+
If you use `allnodes` as the node name, it will compute the catalogs for all nodes that are specified in `site.pp` (this will not work for regexp-specified or the default nodes). This is useful
for writing automated tests, to check a change didn't break something.
+
If you use `deadcode` as the node name, it will also compute the catalogs for all nodes, but will display the list of puppet files that have not been used, and that might be
deprecated.
+
You might want to run the program with `+RTS -N` with those two modes.

`-t` or `--type`::

Filters the resources of the resulting catalog by type, but specifying a regular expression. Only the resources whose types match the submitted regexp will be displayed.

`-n` or `--name`::

Filters the resources of the resulting catalog by name, but specifying a regular expression. Only the resources whose names match the submitted regexp will be displayed.

`-c` or `--showcontent`::

If `-n` is the exact name of a file type resource defined in the catalog, this will display more nicely display the file content. Useful for debugging templates.
Ex: puppetresources -p . -o mynodename -n '/etc/motd' --showcontent

`--loglevel` or `-v`::

Expects a log level. Possible values are : DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY.

`--pdburl`::

Expects the url of a live PuppetDB.

`--pdbfile`::

Expects a path to a *fake* PuppetDB, represented as a YAML file on disk. This option is pretty slow but can be invaluable to test exported resources tricks.

`--hiera`::

Expects the path to the `hiera.yaml` file.

`--ignoremodules`::

Expects a list of comma-separated modules. The interpreter will not try to evaluate the defined types and classes from this module. This is useful for using modules that use bad
practices forbidden by `puppetresources`.

`--nousergrouptest`::

By default, `puppetresources` will check that all users and groups referenced by `cron`, `file`, etc. types are defined somewhere in the catalog (except for a list of widely
available users, such as `root`). This flag disables these tests.

`--commitdb`::

When this flag is set, exported resources, catalogs and facts are saved in the PuppetDB. This is useful in conjunction with `--pdbfile`.

`--checkExported`::

When this flag is set, exported resources are saved in the PuppetDB. This is useful in conjunction with `--pdbfile`.

`-j` or `--JSON`::

Displays the catalog as a Puppet-compatible JSON file, that can then be used with `puppet apply`.

`--facts-override` and `--facts-defaults`::

Both options expect a path to a YAML file defining facts. The first option will override the facts that are collected locally, while the second will merely provide default values
for them.

`--strict`::

Enable strict mode.
The strict mode is less permissive than vanilla Puppet.
It is meant to prevent some pitfalls by enforcing good practices.
For instance it refuses to silently ignore/convert `undef` variables.

== pdbQuery

The `pdbQuery` command is used to work with different implementations of PuppetDB (the official one with its HTTP API, the file-based backend and dummy ones). Its main use is to
export data from production PuppetDB to a file in order to debug some issue with `puppetresources`. Here is a list of command line arguments :

`-l` or `--location`::

The URL of the PuppetDB when working with a remote PuppetDB, a file path when working with the file-based test implementation.

`-t` or `--pdbtype`::

The type of PuppetDB to work with:

* dummy: a dummy PuppetDB.
* remote: a "real" PuppetDB, accessed by its HTTP API.
* test: a file-based backend emulating a PuppetDB.

.Commands
`dumpfacts`::

Dump all facts, and store them in `/tmp/allfacts.yaml`.

`nodes`::

Dump all nodes

`snapshot`::

Create a test DB from the current DB

`addfacts`::

Adds facts to the test DB for the given node name, if they are not already defined.

== Unsupported Puppet idioms or features

puppet functions::
  * the `require` function is not supported (see https://github.com/bartavelle/language-puppet/issues/17[issue #17])
  * the deprecated `import` function is not supported (see https://github.com/bartavelle/language-puppet/issues/82[issue #82])

custom ruby functions::
Currently the only way to support your custom ruby functions is to rewrite them in Lua.

known differences::
Looking up an undef key is silent in Puppet but it is an error with puppetresources.


Fix typo in installation docs

Fix typo in installation docs

[[server-installation]]
= Server Installation

== Deployment Scenarios ==

As a developer, you may wish to download Neo4j and run it locally on your desktop computer.
We recommend this as an easy way to discover Neo4j.

* For Windows, see <<windows-install>>.
* For Unix/Linux, see <<linux-install>>.
* For OSX, see <<osx-install>>.

As a systems administrator, you may wish to install Neo4j using a packaging system so you can ensure that a cluster of machines have identical installs.
See <<linux-packages>> for more information on this.

For information on High Availability, please refer to <<ha>>.

== Prerequisites ==

With the exception of our Windows and Mac Installers, you'll need a Java Virtual Machine installed on your computer.
We recommend that you install http://openjdk.java.net/[OpenJDK 8 (preferred) or 7] or http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle Java 8 (preferred) or 7].

[[server-permissions]]
== Setting Proper File Permissions ==

When installing Neo4j Server, keep in mind that the _bin/neo4j_ executable will need to be run by some OS system user, and that user will need write permissions to some files/directories.
This goes specifically for the _data/graph.db_ directory.
That user will also need execute permissions on other files, such as those in _bin/_.

It is recommended to either choose or create a user who will own and manage the Neo4j Server.
This user should own the entire Neo4j directory, so make sure to untar/unzip it as this user and not with `sudo` (UNIX/Linux/OSx) etc.

If _data/graph.db_ is not writable by the user Neo4j won't be able to write anything either to the store or its log files.
As a result any logs would be appended to _console.log_.
The following error message would indicate a possible permissions issue: `Write transactions to database disabled`.

[[windows-install]]
== Windows ==

[[windows-installer]]
=== Windows Installer ===

1. Download the version that you want from http://neo4j.com/download/.
   * Select the appropriate version and architecture for your platform.
2. Double-click the downloaded installer file.
3. Follow the prompts.

[NOTE]
The installer will prompt to be granted Administrator privileges.
Newer versions of Windows come with a SmartScreen feature that may prevent the installer from running -- you can make it run anyway by clicking "More info" on the "Windows protected your PC" screen.

[TIP]
If you install Neo4j using the windows installer and you already have an existing instance of Neo4j the installer will select a new install directory by default.
If you specify the same directory it will ask if you want to upgrade.
This should proceed without issue although some users have reported a `JRE is damaged` error.
If you see this error simply install Neo4j into a different location.

[[windows-console]]
=== Windows Console Application ===
1. Download the latest release from http://neo4j.com/download/.
   * Select the appropriate Zip distribution.
2. Right-click the downloaded file, click Extract All.
   * Refer to the top-level extracted directory as: +NEO4J_HOME+
3. Consult <<powershell>> for how to start or install Neo4j.

[NOTE]
Some users have reported problems on Windows when using the ZoneAlarm firewall.
If you are having problems getting large responses from the server, or if the web interface does not work, try disabling ZoneAlarm.
Contact ZoneAlarm support to get information on how to resolve this.

[[linux-install]]
== Linux ==

[[linux-packages]]
=== Linux Packages ===

* For Debian packages, see the instructions at  http://debian.neo4j.org/.

After installation you may have to do some platform specific configuration and performance tuning.
For that, refer to <<performance-guide>>.

[[unix-console]]
=== Unix Console Application ===

1. Download the latest release from http://neo4j.com/download/.
   * Select the appropriate tar.gz distribution for your platform.
2. Extract the contents of the archive, using: `tar -xf <filename>`
   * Refer to the top-level extracted directory as: +NEO4J_HOME+
3. Change directory to: `$NEO4J_HOME`
   * Run: `./bin/neo4j console`
4. Stop the server by typing Ctrl-C in the console.

=== Linux Service ===

The `neo4j` command can also be used with `start`, `stop`, `restart` or `status` instead of `console`.
By using these actions, you can create a Neo4j service.
See the <<neo4j-manpage,neo4j man page>> for further details.

[CAUTION]
This approach to running Neo4j as a service is deprecated.
We strongly advise you to run Neo4j from a package where feasible.

You can build your own `init.d` script.
See for instance the Linux Standard Base specification on http://refspecs.linuxfoundation.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/tocsysinit.html[system initialization], or one of the many https://gist.github.com/chrisvest/7673244[samples] and http://www.linux.com/learn/tutorials/442412-managing-linux-daemons-with-init-scripts[tutorials].

[[osx-install]]
== Mac OSX ==

=== Mac OSX Installer ===

1. Download the _.dmg_ installer that you want from http://neo4j.com/download/.
2. Click the downloaded installer file.
3. Drag the Neo4j icon into the Applications folder.

[TIP]
If you install Neo4j using the Mac installer and already have an existing instance of Neo4j the installer will ensure that both the old and new versions can co-exist on your system.

=== Running Neo4j from the Terminal ===

The server can be started in the background from the terminal with the command `neo4j start`, and then stopped again with `neo4j stop`.
The server can also be started in the foreground with `neo4j console` -- then it's log output will be printed to the terminal.

The `neo4j-shell` command can be used to interact with Neo4j from the command line using Cypher. It will automatically connect to any
server that is running on localhost with the default port, otherwise it will show a help message. You can alternatively start the
shell with an embedded Neo4j instance, by using the `-path path/to/data` argument -- note that only a single instance of Neo4j
can access the database files at a time.

=== OSX Service ===

Use the standard OSX system tools to create a service based on the `neo4j` command.

=== A note on Java on OS X Mavericks ===

Unlike previous versions, OS X Mavericks does not come with Java pre-installed. You might encounter that the first time you run Neo4j, where OS X will trigger a popup offering you to install Java SE 6.

Java SE 6 is incompatible with Neo4j {neo4j-version}, so we strongly advise you to skip installing Java SE 6 if you have no other uses for it. Instead, for Neo4j {neo4j-version} we recommend you install Java SE 8 (preferred) or 7 from Oracle (http://www.oracle.com/technetwork/java/javase/downloads/index.html) as that is what we support for production use.

== Multiple Server instances on one machine ==

Neo4j can be set up to run as several instances on one machine, providing for instance several databases for development.

For how to set this up, see <<ha-local-cluster>>.
Just use the Neo4j edition of your choice, follow the guide and remember to not set the servers to run in HA mode.

[[server-installation]]
= Server Installation

== Deployment Scenarios ==

As a developer, you may wish to download Neo4j and run it locally on your desktop computer.
We recommend this as an easy way to discover Neo4j.

* For Windows, see <<windows-install>>.
* For Unix/Linux, see <<linux-install>>.
* For OSX, see <<osx-install>>.

As a systems administrator, you may wish to install Neo4j using a packaging system so you can ensure that a cluster of machines have identical installs.
See <<linux-packages>> for more information on this.

For information on High Availability, please refer to <<ha>>.

== Prerequisites ==

With the exception of our Windows and Mac Installers, you'll need a Java Virtual Machine installed on your computer.
We recommend that you install http://openjdk.java.net/[OpenJDK 8 (preferred) or 7] or http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle Java 8 (preferred) or 7].

[[server-permissions]]
== Setting Proper File Permissions ==

When installing Neo4j Server, keep in mind that the _bin/neo4j_ executable will need to be run by some OS system user, and that user will need write permissions to some files/directories.
This goes specifically for the _data/graph.db_ directory.
That user will also need execute permissions on other files, such as those in _bin/_.

It is recommended to either choose or create a user who will own and manage the Neo4j Server.
This user should own the entire Neo4j directory, so make sure to untar/unzip it as this user and not with `sudo` (UNIX/Linux/OSx) etc.

If _data/graph.db_ is not writable by the user Neo4j won't be able to write anything either to the store or its log files.
As a result any logs would be appended to _console.log_.
The following error message would indicate a possible permissions issue: `Write transactions to database disabled`.

[[windows-install]]
== Windows ==

[[windows-installer]]
=== Windows Installer ===

1. Download the version that you want from http://neo4j.com/download/.
   * Select the appropriate version and architecture for your platform.
2. Double-click the downloaded installer file.
3. Follow the prompts.

[NOTE]
The installer will prompt to be granted Administrator privileges.
Newer versions of Windows come with a SmartScreen feature that may prevent the installer from running -- you can make it run anyway by clicking "More info" on the "Windows protected your PC" screen.

[TIP]
If you install Neo4j using the windows installer and you already have an existing instance of Neo4j the installer will select a new install directory by default.
If you specify the same directory it will ask if you want to upgrade.
This should proceed without issue although some users have reported a `JRE is damaged` error.
If you see this error simply install Neo4j into a different location.

[[windows-console]]
=== Windows Console Application ===
1. Download the latest release from http://neo4j.com/download/.
   * Select the appropriate Zip distribution.
2. Right-click the downloaded file, click Extract All.
   * Refer to the top-level extracted directory as: +NEO4J_HOME+
3. Consult <<powershell>> for how to start or install Neo4j.

[NOTE]
Some users have reported problems on Windows when using the ZoneAlarm firewall.
If you are having problems getting large responses from the server, or if the web interface does not work, try disabling ZoneAlarm.
Contact ZoneAlarm support to get information on how to resolve this.

[[linux-install]]
== Linux ==

[[linux-packages]]
=== Linux Packages ===

* For Debian packages, see the instructions at  http://debian.neo4j.org/.

After installation you may have to do some platform specific configuration and performance tuning.
For that, refer to <<performance-guide>>.

[[unix-console]]
=== Unix Console Application ===

1. Download the latest release from http://neo4j.com/download/.
   * Select the appropriate tar.gz distribution for your platform.
2. Extract the contents of the archive, using: `tar -xf <filename>`
   * Refer to the top-level extracted directory as: +NEO4J_HOME+
3. Change directory to: `$NEO4J_HOME`
   * Run: `./bin/neo4j console`
4. Stop the server by typing Ctrl-C in the console.

=== Linux Service ===

The `neo4j` command can also be used with `start`, `stop`, `restart` or `status` instead of `console`.
By using these actions, you can create a Neo4j service.
See the <<neo4j-manpage,neo4j man page>> for further details.

[CAUTION]
This approach to running Neo4j as a server is deprecated.
We strongly advise you to run Neo4j from a package where feasible.

You can build your own `init.d` script.
See for instance the Linux Standard Base specification on http://refspecs.linuxfoundation.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/tocsysinit.html[system initialization], or one of the many https://gist.github.com/chrisvest/7673244[samples] and http://www.linux.com/learn/tutorials/442412-managing-linux-daemons-with-init-scripts[tutorials].

[[osx-install]]
== Mac OSX ==

=== Mac OSX Installer ===

1. Download the _.dmg_ installer that you want from http://neo4j.com/download/.
2. Click the downloaded installer file.
3. Drag the Neo4j icon into the Applications folder.

[TIP]
If you install Neo4j using the Mac installer and already have an existing instance of Neo4j the installer will ensure that both the old and new versions can co-exist on your system.

=== Running Neo4j from the Terminal ===

The server can be started in the background from the terminal with the command `neo4j start`, and then stopped again with `neo4j stop`.
The server can also be started in the foreground with `neo4j console` -- then it's log output will be printed to the terminal.

The `neo4j-shell` command can be used to interact with Neo4j from the command line using Cypher. It will automatically connect to any
server that is running on localhost with the default port, otherwise it will show a help message. You can alternatively start the
shell with an embedded Neo4j instance, by using the `-path path/to/data` argument -- note that only a single instance of Neo4j
can access the database files at a time.

=== OSX Service ===

Use the standard OSX system tools to create a service based on the `neo4j` command.

=== A note on Java on OS X Mavericks ===

Unlike previous versions, OS X Mavericks does not come with Java pre-installed. You might encounter that the first time you run Neo4j, where OS X will trigger a popup offering you to install Java SE 6.

Java SE 6 is incompatible with Neo4j {neo4j-version}, so we strongly advise you to skip installing Java SE 6 if you have no other uses for it. Instead, for Neo4j {neo4j-version} we recommend you install Java SE 8 (preferred) or 7 from Oracle (http://www.oracle.com/technetwork/java/javase/downloads/index.html) as that is what we support for production use.

== Multiple Server instances on one machine ==

Neo4j can be set up to run as several instances on one machine, providing for instance several databases for development.

For how to set this up, see <<ha-local-cluster>>.
Just use the Neo4j edition of your choice, follow the guide and remember to not set the servers to run in HA mode.


- Feature update.

- Feature update.

= Forklift

The Enterprise Service Bus that supports building and deploying microservices quickly
and easily. Forklift makes your life easier by providing common functionality that can
be shared by easily by annotating your code. To see what it can do for you check out the
full documentation.

link:doc/forklift.adoc[Documentation]

== Releases
link:doc/prev_releases.adoc[Previous Releases]

* v1.0
** Kafka Connector
** Core no longer depends on the JMS spec libraries

= Forklift

The Enterprise Service Bus that supports building and deploying microservices quickly
and easily. Forklift makes your life easier by providing common functionality that can
be shared by easily by annotating your code. To see what it can do for you check out the
full documentation.

link:doc/forklift.adoc[Documentation]

== Releases
link:doc/prev_releases.adoc[Previous Releases]

* v1.0
** Kafka Connector
** Core no longer depends on the JMS specific


Fix: 解决在Ubuntu平台编译出错的问题

Fix: 解决在Ubuntu平台编译出错的问题

= rmgt

Linux and Windows Remote Management, 方便快捷的远程服务器连接工具

== 平台
支持 Linux(SSH) 以及 Windows(RDP) 远程连接

.Linux
* 支持证书登录
* 支持密码登录

.Windows
* 仅支持密码登录

== 编译安装
=== 安装 Google Test
ArchLinux:: sudo pacman -S cmake g++ gtest sshpass openssl
Ubuntu:: sudo apt-get install cmake g++ libgtest-dev libssl-dev sshpass
Ubuntu 18.04:: sudo apt-get install cmake g++ googletest libssl-dev sshpass
CentOS:: sudo yum install epel-release && sudo yum install cmake gcc-c++ gtest-devel sshpass openssl-devel

.Ubuntu平台需要手动解决单元测试依赖
----
mkdir /tmp/gtest_build
cd /tmp/gtest_build
cmake /usr/src/googletest/googletest/
sudo cp libgtest.a libgtest_main.a /usr/local/lib/
cd ~
rm -rf /tmp/gtest_build
----

.编译rmgt
----
$ git clone https://github.com/fifilyu/rmgt.git
$ mkdir rmgt_build
$ cd rmgt_build
$ cmake ../rmgt
$ make
$ make test
$ cp bin/rmgt 任意路径 (比如，cp bin/rmgt /home/fifilyu/bin/rmgt)
----

[NOTE]
建议将 rmgt 所在目录 (比如，/home/fifilyu/bin) 加入环境变量 `$PATH` ，也可直接复制到 `/usr/local/bin`，以使任意位置都能找到 `rmgt` 命令。

== 配置文件
主机信息将会保存到当前用户主目录下，文件名为 `.rmgt.conf`。比如，/home/fifilyu/.rmgt.conf

=== 安全
rmgt 将以明文保存主机信息，包括 *密码* 。

[WARNING]
现在，如果你对安全问题非常敏感，请 *慎用* rmgt 。

== 连接 Windows 主机的分辨率设置
默认分辨率是 800 * 600。如果需要重置分辨率，请直接修改 main.cxx 中 `"-g800x600 "` 即可。

== 用法

=== 安装软件包
.说明
openssh:: SSH 协议工具集
rdesktop:: Windows 远程桌面协议(RDP)客户端
sshpass:: 非交互式 SSH 密码工具

.安装软件
ArchLinux:: sudo pacman -S openssh rdesktop sshpass
Ubuntu:: sudo apt-get install openssh-client rdesktop sshpass
CentOS:: sudo yum install openssh-clients rdesktop sshpass (需要 EPEL 源)

=== 增加主机

==== Linux 平台
*证书登录*

`rmgt -n usa241 -o linux -i 142.4.114.xxx -p 22 -u root -d "美国代理线路"`

or

`rmgt -n usa241 -o linux -i 142.4.114.xxx`

*密码登录*

`rmgt -n usa241 -o linux -i 142.4.114.xxx -p 22 -u root -w password -d "美国代理线路"`

or

`rmgt -n usa241 -o linux -i 142.4.114.xxx -w password`

==== Windows 平台
*密码登录*

`rmgt -n ali44 -o windows -i 121.41.45.xxx -p 3389 -u administrator -w password -d "阿里云"`

or

`rmgt -n ali44 -o windows -i 121.41.45.xxx`

=== 连接主机

Linux: 必须在终端下执行 `rmgt -c usa241`

Windows: 在终端或者 X 桌面下执行 `rmgt -c ali44`

=== 删除主机

`rmgt -r usa241`

`rmgt -r ali44`

== 使用详情
请 `rmgt -h` 查看帮助

----
rmgt(remote management) v2.0.1 - 方便快捷的远程服务器连接工具

用法 :
	rmgt -V
	rmgt -c <主机名> [-v]
	rmgt -l
	rmgt -s <主机名>
	rmgt -r <主机名>
	rmgt -n <主机名> -o <操作系统> -i <IP地址> -p [远程端口[22|3389]] -u [用户名[root|administrator]] -w [密码] -d [描述]

参数 :
	-c <主机名>		将连接的主机名
	-l 			显示所有主机信息
	-s <主机名>		显示指定主机信息
	-r <主机名>		从配置文件删除主机
	-n <主机名>		增加主机时，设置主机名
	-o <操作系统>		增加主机时，设置操作系统，可选值：linux windows
	-i <IP地址>		增加主机时，设置IP地址
	-p [远程端口]		增加主机时，设置远程端口，linux 默认值：22，windows 默认值：3389
	-u [用户名]		增加主机时，设置远程登录用户名，linux 默认值：root，windows 默认值：administrator
	-w [密码]		增加主机时，设置密码，默认值：空
	-d [描述]		增加主机时，设置描述，默认值：空
	-h <显示帮助信息>	显示帮助信息
	-v <显示连接信息>	显示连接信息
	-V <显示版本信息>	显示版本信息
----

= rmgt

Linux and Windows Remote Management, 方便快捷的远程服务器连接工具

== 平台
支持 Linux(SSH) 以及 Windows(RDP) 远程连接

.Linux
* 支持证书登录
* 支持密码登录

.Windows
* 仅支持密码登录

== 编译安装
=== 安装 Google Test
ArchLinux:: sudo pacman -S cmake g++ gtest sshpass openssl
Ubuntu:: sudo apt-get install cmake g++ libgtest-dev libssl-dev sshpass
Ubuntu 18.04:: sudo apt-get install cmake g++ googletest libssl-dev sshpass
CentOS:: sudo yum install epel-release && sudo yum install cmake gcc-c++ gtest-devel sshpass openssl-devel

----
$ git clone https://github.com/fifilyu/rmgt.git
$ mkdir rmgt_build
$ cd rmgt_build
$ cmake ../rmgt
$ make
$ make test
$ cp bin/rmgt 任意路径 (比如，cp bin/rmgt /home/fifilyu/bin/rmgt)
----

[NOTE]
建议将 rmgt 所在目录 (比如，/home/fifilyu/bin) 加入环境变量 `$PATH` ，也可直接复制到 `/usr/local/bin`，以使任意位置都能找到 `rmgt` 命令。

== 配置文件
主机信息将会保存到当前用户主目录下，文件名为 `.rmgt.conf`。比如，/home/fifilyu/.rmgt.conf

=== 安全
rmgt 将以明文保存主机信息，包括 *密码* 。

[WARNING]
现在，如果你对安全问题非常敏感，请 *慎用* rmgt 。

== 连接 Windows 主机的分辨率设置
默认分辨率是 800 * 600。如果需要重置分辨率，请直接修改 main.cxx 中 `"-g800x600 "` 即可。

== 用法

=== 安装软件包
.说明
openssh:: SSH 协议工具集
rdesktop:: Windows 远程桌面协议(RDP)客户端
sshpass:: 非交互式 SSH 密码工具

.安装软件
ArchLinux:: sudo pacman -S openssh rdesktop sshpass
Ubuntu:: sudo apt-get install openssh-client rdesktop sshpass
CentOS:: sudo yum install openssh-clients rdesktop sshpass (需要 EPEL 源)

=== 增加主机

==== Linux 平台
*证书登录*

`rmgt -n usa241 -o linux -i 142.4.114.xxx -p 22 -u root -d "美国代理线路"`

or

`rmgt -n usa241 -o linux -i 142.4.114.xxx`

*密码登录*

`rmgt -n usa241 -o linux -i 142.4.114.xxx -p 22 -u root -w password -d "美国代理线路"`

or

`rmgt -n usa241 -o linux -i 142.4.114.xxx -w password`

==== Windows 平台
*密码登录*

`rmgt -n ali44 -o windows -i 121.41.45.xxx -p 3389 -u administrator -w password -d "阿里云"`

or

`rmgt -n ali44 -o windows -i 121.41.45.xxx`

=== 连接主机

Linux: 必须在终端下执行 `rmgt -c usa241`

Windows: 在终端或者 X 桌面下执行 `rmgt -c ali44`

=== 删除主机

`rmgt -r usa241`

`rmgt -r ali44`

== 使用详情
请 `rmgt -h` 查看帮助

----
rmgt(remote management) v2.0.1 - 方便快捷的远程服务器连接工具

用法 :
	rmgt -V
	rmgt -c <主机名> [-v]
	rmgt -l
	rmgt -s <主机名>
	rmgt -r <主机名>
	rmgt -n <主机名> -o <操作系统> -i <IP地址> -p [远程端口[22|3389]] -u [用户名[root|administrator]] -w [密码] -d [描述]

参数 :
	-c <主机名>		将连接的主机名
	-l 			显示所有主机信息
	-s <主机名>		显示指定主机信息
	-r <主机名>		从配置文件删除主机
	-n <主机名>		增加主机时，设置主机名
	-o <操作系统>		增加主机时，设置操作系统，可选值：linux windows
	-i <IP地址>		增加主机时，设置IP地址
	-p [远程端口]		增加主机时，设置远程端口，linux 默认值：22，windows 默认值：3389
	-u [用户名]		增加主机时，设置远程登录用户名，linux 默认值：root，windows 默认值：administrator
	-w [密码]		增加主机时，设置密码，默认值：空
	-d [描述]		增加主机时，设置描述，默认值：空
	-h <显示帮助信息>	显示帮助信息
	-v <显示连接信息>	显示连接信息
	-V <显示版本信息>	显示版本信息
----