Repository: syncope Updated Branches: refs/heads/master aeb3aac81 -> 8efa3701e
[SYNCOPE-700] Moving CLI setp to getting started; added eclipse plugin Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/8efa3701 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/8efa3701 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/8efa3701 Branch: refs/heads/master Commit: 8efa3701ebb65f328d64b3fb600532b428c8d238 Parents: aeb3aac Author: Francesco Chicchiriccò <ilgro...@apache.org> Authored: Mon Jul 25 17:35:38 2016 +0200 Committer: Francesco Chicchiriccò <ilgro...@apache.org> Committed: Mon Jul 25 17:35:38 2016 +0200 ---------------------------------------------------------------------- src/main/asciidoc/getting-started/obtain.adoc | 232 +++++++++++++++++++ src/main/asciidoc/images/eclipse01.png | Bin 0 -> 35891 bytes src/main/asciidoc/images/eclipse02.png | Bin 0 -> 18227 bytes src/main/asciidoc/images/eclipse03.png | Bin 0 -> 4809 bytes src/main/asciidoc/images/eclipse04.png | Bin 0 -> 11377 bytes src/main/asciidoc/images/eclipse05.png | Bin 0 -> 51446 bytes src/main/asciidoc/images/eclipse06.png | Bin 0 -> 57532 bytes src/main/asciidoc/images/eclipse07.png | Bin 0 -> 24895 bytes src/main/asciidoc/images/eclipse08.png | Bin 0 -> 10020 bytes src/main/asciidoc/images/eclipse09.png | Bin 0 -> 7757 bytes src/main/asciidoc/images/eclipse10.png | Bin 0 -> 33757 bytes src/main/asciidoc/images/eclipse11.png | Bin 0 -> 8725 bytes src/main/asciidoc/images/eclipse12.png | Bin 0 -> 5290 bytes src/main/asciidoc/images/eclipse13.png | Bin 0 -> 15589 bytes src/main/asciidoc/images/eclipse14.png | Bin 0 -> 12249 bytes src/main/asciidoc/images/eclipse15.png | Bin 0 -> 21187 bytes .../workingwithapachesyncope/cli/cli.adoc | 8 +- .../cli/installation.adoc | 181 --------------- src/site/xdoc/downloads.xml | 6 + 19 files changed, 239 insertions(+), 188 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/getting-started/obtain.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/getting-started/obtain.adoc b/src/main/asciidoc/getting-started/obtain.adoc index aab53cc..841914f 100644 --- a/src/main/asciidoc/getting-started/obtain.adoc +++ b/src/main/asciidoc/getting-started/obtain.adoc @@ -487,3 +487,235 @@ You can configure any LDAP client (as http://jxplorer.org/[JXplorer^], for examp Click 'Connect' button |=== + +=== CLI + +The command-line interface (CLI) client is an utility tool meant for interacting with Apache Syncope deployments from +shell scripts. + +Once downloaded and uncompressed, you will find a `lib` directory and two scripts: `syncopeadm.sh` and `syncopeadm.bat`, +which will be used depending on the operating system. + +The installation process creates `cli.properties`, which contains all the required information to invoke the Apache +Syncope REST API services. +The file content looks like the following: + +[source] +syncope.rest.services=http://localhost:9080/syncope/rest +syncope.admin.user=admin +syncope.admin.password=QePSFVTnzwQowM4ohhaUYcE6aW47MVZ/ + +where: + +syncope.rest.services:: + the base URL where the Apache Syncope REST API services are listening; +syncope.admin.user:: + the username which will be used to invoke the Syncope APIs; +syncope.admin.password:: + the password for the admin user configured above. + +As shown above, the password value is encrypted for security reasons. + +[discrete] +===== Help message +[source,bash] +---- +Usage: install [options] + Options: + --help + --setup + --setup-debug +---- + +==== Installation +After the file is unzipped you can start with CLI client using the `syncopeadm` file. +If you have tried to run a CLI command before the installation process, the script will return +[source] +-- + - Error: It seems you need to first setup the CLI client. Run install --setup. +-- + +So, as suggested, you have to run the install command to use the CLI: +[source] +-- +$ ./syncopeadm.sh install --setup +-- + +A successful result will be: +[source,bash,subs="verbatim,attributes"] +---- + +You are running: install --setup + +############################################### +# # +# Welcome to Syncope CLI installation process # +# # +############################################### + +Path to config files of Syncope CLI client will be: ./ +- File system permission checked + +Syncope server schema [http/https]: http +Syncope server hostname [e.g. localhost]: localhost +Syncope server port [e.g. 8080]: 9080 +Syncope server rest context [e.g. /syncope/rest/]: /syncope/rest +Syncope admin user: admin +Syncope admin password: password +Installation parameters checked on Syncope core version: {docVersion} + +############################################### +# # +# Installation successful # +# now you can use Syncope CLI client # +# # +############################################### + +---- + +During the installation you have to provide: + +Syncope server schema:: + the http protocol used by the Apache Syncope core, it will be http or https; +Syncope server hostname:: + the hostname where the core is deployed; +Syncope server port:: + the port where the services are listening; +Syncope server rest context:: + the context where the rest services are deployed (/syncope/rest is the default); +Syncope admin user:: + the user with the permission to call the Syncope APIs; +Syncope admin password:: + the user password. + +==== Troubleshooting +Various error messages are possible on installation. Here are some sample error messages: + +===== Syncope unreachable (or wrong address): + +[source] +-- + +Provided address: http://localhost:9080/syncope/rest + +############################################### +# # +# Provided address is unreachable! # +# Check it and if it is wrong # +# START the installation AGAIN! # +# # +############################################### + +-- + +===== Authentication failed: + +[source] +-- + +############################################### +# # +# Username or password provided are wrong # +# START the installation AGAIN! # +# # +############################################### + +-- + +As the message suggests you have to start the installation again when this error occurrs. + + +==== Debug +To work with the debug environment provided by Syncope we added a particular installation option for it. +It enough to run the script with the --setup-debug option +[source] +-- +$ ./syncopeadm.sh install --setup-debug +-- +[source,bash,subs="verbatim,attributes"] +---- + +You are running: install --setup-debug + +############################################### +# # +# Welcome to Syncope CLI installation process # +# # +############################################### + +Path to config files of Syncope CLI client will be: ./ +- File system permission checked + +Installation parameters checked on Syncope core version: {docVersion} + +############################################### +# # +# Installation successful # +# now you can use Syncope CLI client # +# # +############################################### + +---- + +=== Eclipse IDE Plugin + +The Eclipse IDE plugin allows remote management of notification e-mail and report templates. + +==== Installation + +After http://syncope.apache.org/downloads.html[download^], start the most recent Eclipse IDE distribution then go to +`Help > Install New Software`: + +image::eclipse01.png[eclipse01] + +Click on `Add`: + +image::eclipse02.png[eclipse02] + +Click on `Local` then `Archive` and find the downloaded zip file: + +image::eclipse03.png[eclipse03] + +image::eclipse04.png[eclipse04] + +image::eclipse05.png[eclipse05] + +Select `Apache Syncope` and click on `Next`: + +image::eclipse06.png[eclipse06] + +Click on `Finish` and wait for installation to complete: + +image::eclipse07.png[eclipse07] + +image::eclipse08.png[eclipse08] + +image::eclipse09.png[eclipse09] + +==== Setup + +After Eclipse IDE restart, go to `Window` > `Show View` > `Other` + +image::eclipse10.png[eclipse10] + +Select `Apache Syncope Templates`: + +image::eclipse11.png[eclipse11] + +In the new view, click on `Login`: + +image::eclipse12.png[eclipse12] + +Provide the base URL for Apache Syncope deployment, username and password: + +image::eclipse13.png[eclipse13] + +If the information above is correct, two folders should now appear: + +image::eclipse14.png[eclipse14] + +By double-clicking on each folder, the list of available templates is shown: + +image::eclipse15.png[eclipse15] + +Each template is now ready for authoring or removal; new templates can also be created. http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse01.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse01.png b/src/main/asciidoc/images/eclipse01.png new file mode 100644 index 0000000..0fb85a6 Binary files /dev/null and b/src/main/asciidoc/images/eclipse01.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse02.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse02.png b/src/main/asciidoc/images/eclipse02.png new file mode 100644 index 0000000..708c9a5 Binary files /dev/null and b/src/main/asciidoc/images/eclipse02.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse03.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse03.png b/src/main/asciidoc/images/eclipse03.png new file mode 100644 index 0000000..39d78a5 Binary files /dev/null and b/src/main/asciidoc/images/eclipse03.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse04.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse04.png b/src/main/asciidoc/images/eclipse04.png new file mode 100644 index 0000000..1a09a6d Binary files /dev/null and b/src/main/asciidoc/images/eclipse04.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse05.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse05.png b/src/main/asciidoc/images/eclipse05.png new file mode 100644 index 0000000..cb5c0b2 Binary files /dev/null and b/src/main/asciidoc/images/eclipse05.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse06.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse06.png b/src/main/asciidoc/images/eclipse06.png new file mode 100644 index 0000000..8d0fdf6 Binary files /dev/null and b/src/main/asciidoc/images/eclipse06.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse07.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse07.png b/src/main/asciidoc/images/eclipse07.png new file mode 100644 index 0000000..fa8f265 Binary files /dev/null and b/src/main/asciidoc/images/eclipse07.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse08.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse08.png b/src/main/asciidoc/images/eclipse08.png new file mode 100644 index 0000000..7018c58 Binary files /dev/null and b/src/main/asciidoc/images/eclipse08.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse09.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse09.png b/src/main/asciidoc/images/eclipse09.png new file mode 100644 index 0000000..5002915 Binary files /dev/null and b/src/main/asciidoc/images/eclipse09.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse10.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse10.png b/src/main/asciidoc/images/eclipse10.png new file mode 100644 index 0000000..2d29368 Binary files /dev/null and b/src/main/asciidoc/images/eclipse10.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse11.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse11.png b/src/main/asciidoc/images/eclipse11.png new file mode 100644 index 0000000..d5d95b2 Binary files /dev/null and b/src/main/asciidoc/images/eclipse11.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse12.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse12.png b/src/main/asciidoc/images/eclipse12.png new file mode 100644 index 0000000..7e30bf8 Binary files /dev/null and b/src/main/asciidoc/images/eclipse12.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse13.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse13.png b/src/main/asciidoc/images/eclipse13.png new file mode 100644 index 0000000..45502f3 Binary files /dev/null and b/src/main/asciidoc/images/eclipse13.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse14.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse14.png b/src/main/asciidoc/images/eclipse14.png new file mode 100644 index 0000000..8f5f5f8 Binary files /dev/null and b/src/main/asciidoc/images/eclipse14.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/images/eclipse15.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/eclipse15.png b/src/main/asciidoc/images/eclipse15.png new file mode 100644 index 0000000..044e78b Binary files /dev/null and b/src/main/asciidoc/images/eclipse15.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/cli.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/cli.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/cli.adoc index 71a7246..98f55e3 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/cli.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/cli.adoc @@ -18,14 +18,8 @@ // === CLI -Once you have downloaded and unzipped the zip file containing the scripts, you will find a `lib` directory and -two scripts: `syncopeadm.sh` and `syncopeadm.bat`. -You will use one of these files, depending on your operating system. - [NOTE] -Every example described in this document is executed on a GNU / Linux machine with a _debug environment_. - -include::installation.adoc[] +Examples in this document are executed on GNU / Linux with _debug environment_. ==== Commands http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/installation.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/installation.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/installation.adoc deleted file mode 100644 index 52a42a1..0000000 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/cli/installation.adoc +++ /dev/null @@ -1,181 +0,0 @@ -// -// Licensed to the Apache Software Foundation (ASF) under one -// or more contributor license agreements. See the NOTICE file -// distributed with this work for additional information -// regarding copyright ownership. The ASF licenses this file -// to you under the Apache License, Version 2.0 (the -// "License"); you may not use this file except in compliance -// with the License. You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. -// - -==== Initial Setup -The installation process creates `cli.properties`, which contains all the required information to invoke the Apache -Syncope REST API services. -The file content looks like the following: - -[source] -syncope.rest.services=http://localhost:9080/syncope/rest -syncope.admin.user=admin -syncope.admin.password=QePSFVTnzwQowM4ohhaUYcE6aW47MVZ/ - -where: - -syncope.rest.services:: - the base URL where the Apache Syncope REST API services are listening; -syncope.admin.user:: - the username which will be used to invoke the Syncope APIs; -syncope.admin.password:: - the password for the admin user configured above. - -As shown above, the password value is encrypted for security reasons. - -[discrete] -====== Help message -[source,bash] ----- -Usage: install [options] - Options: - --help - --setup - --setup-debug ----- - -===== Run the installation -After the zip file is unzipped you can start with CLI client using the syncopeadm file. -If you tried to run a CLI command before the installation process, the script returns -[source] --- - - Error: It seems you need to first setup the CLI client. Run install --setup. --- - -So, as suggested, you have to run the install command to use the CLI: -[source] --- -$ ./syncopeadm.sh install --setup --- - -A successful result will be: -[source,bash,subs="verbatim,attributes"] ----- - -You are running: install --setup - -############################################### -# # -# Welcome to Syncope CLI installation process # -# # -############################################### - -Path to config files of Syncope CLI client will be: ./ -- File system permission checked - -Syncope server schema [http/https]: http -Syncope server hostname [e.g. localhost]: localhost -Syncope server port [e.g. 8080]: 9080 -Syncope server rest context [e.g. /syncope/rest/]: /syncope/rest -Syncope admin user: admin -Syncope admin password: password -Installation parameters checked on Syncope core version: {docVersion} - -############################################### -# # -# Installation successful # -# now you can use Syncope CLI client # -# # -############################################### - ----- - -During the installation you have to provide: - -Syncope server schema:: - the http protocol used by the Apache Syncope core, it will be http or https; -Syncope server hostname:: - the hostname where the core is deployed; -Syncope server port:: - the port where the services are listening; -Syncope server rest context:: - the context where the rest services are deployed (/syncope/rest is the default); -Syncope admin user:: - the user with the permission to call the Syncope APIs; -Syncope admin password:: - the user password. - -===== Installation error -Various error messages are possible on installation. Here are some sample error messages: - -* Syncope unreachable (or wrong address): - -[source] --- - -Provided address :http://localhost:9080/syncope/rest - -############################################### -# # -# Provided address is unreachable! # -# Check it and if it is wrong # -# START the installation AGAIN! # -# # -############################################### - --- - -* Authentication failed: - -[source] --- - -############################################### -# # -# Username or password provided are wrong # -# START the installation AGAIN! # -# # -############################################### - --- - -As the message suggests you have to start the installation again when this error occurrs. - - -===== Debug installation -To work with the debug environment provided by Syncope we added a particular installation option for it. -It enough to run the script with the --setup-debug option -[source] --- -$ ./syncopeadm.sh install --setup-debug --- -[source,bash,subs="verbatim,attributes"] ----- - -You are running: install --setup-debug - -############################################### -# # -# Welcome to Syncope CLI installation process # -# # -############################################### - -Path to config files of Syncope CLI client will be: ./ -- File system permission checked - -Installation parameters checked on Syncope core version: {docVersion} - -############################################### -# # -# Installation successful # -# now you can use Syncope CLI client # -# # -############################################### - ----- - http://git-wip-us.apache.org/repos/asf/syncope/blob/8efa3701/src/site/xdoc/downloads.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/downloads.xml b/src/site/xdoc/downloads.xml index a604b78..2c1afc7 100644 --- a/src/site/xdoc/downloads.xml +++ b/src/site/xdoc/downloads.xml @@ -52,6 +52,12 @@ under the License. <li> <a href="docs/getting-started.html#maven-project">Maven Project</a> </li> + <li> + <a href="docs/getting-started.html#cli">CLI</a> + </li> + <li> + <a href="docs/getting-started.html#eclipse-ide-plugin">Eclipse IDE Plugin</a> + </li> </ul> </p>
