8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson<?xml version="1.0" encoding="UTF-8"?>

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson<chapter xml:id='chap-install'

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson xmlns='http://docbook.org/ns/docbook'

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson version='5.0' xml:lang='en'

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

429e23d2f56d28d86439f75c13cda2b4ac5ab67bMark Andrews xmlns:xlink='http://www.w3.org/1999/xlink'

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson xmlns:xinclude='http://www.w3.org/2001/XInclude'>

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson <title>Installing OpenIDM Services</title>

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson <para>This chapter covers the tasks required to install the OpenIDM services.</para>

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson <section>

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson <title>Before You Run OpenIDM</title>

8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson

<para>This section covers what you need to know before running OpenIDM.

</para>

<section>

<title>Java Environment</title>

<para>OpenIDM requires requires Oracle Java SE JDK 6, update 24 or

later.</para>

<para>The equivalent version of OpenJDK should work too.</para>

</section>

<section>

<title>Application Container</title>

<para>The OpenIDM services run in an OSGi container with an embedded servlet

container and an embedded noSQL database. By default the OSGi container is

Apache Felix, the servlet container is Jetty, and the noSQL database is

OrientDB. At this time the only supported configuration is running the services

in Apache Felix.

</para>

</section>

<section>

<title>Installing &amp; Running OpenIDM</title>

<procedure>

<title>Install the OpenIDM Services</title>

<step>

<para>Make sure you have the correct version of Java installed.</para>

<screen width='100' >$ java -version

java version "1.6.0_24"

Java(TM) SE Runtime Environment (build 1.6.0_24-b07-334)

Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02-334, mixed mode)</screen>

</step>

<step>

<para>Download OpenIDM from the <link

xlink:href='http://forgerock.org/openidm.html'>downloads page</link>.</para>

</step>

<step>

<para>Unpack the contents of the .zip file into the install location.</para>

<screen width='100' >$ cd /path/to

$ unzip ~/Downloads/openidm-*.zip

...

inflating: openidm/src/site/index.htm

$ </screen>

</step>

<step performance="optional">

<para>By default the OpenIDM servlet container is listening on port 8080. To

change the default port you must modify

the <literal>org.osgi.service.http.port</literal> property in

<filename>openidm/conf/config.properties</filename>.</para></step>

</procedure>

<procedure>

<title>Start the OpenIDM Services</title>

<note>

<para>

In the current build of OpenIDM the reconciliation sample is

enabled by default. The sample consists of a source and a target

connector and a reconcilation task scheduled to run every minute.

To learn more about the sample please refer to

Chapter 3. To disable the sample you may set the "enabled" attribute to "false" in the

scheduler configuration file at

</para>

<para>

<filename>conf/scheduler-reconcile_systemXmlAccounts_managedUser.json</filename>

</para></note>

<step>

<para>

The following will start the Felix container, load all the OpenIDM services

and start a command shell to allow you to manage the container.

</para>

<screen width='100'>$ cd /path/to/openidm

$ /start.sh

Do you want to start in debug mode: [y]n

Listening for transport dt_socket at address: 5005

...

-&gt;</screen>

<para>

Windows

</para>

<screen width='100'>$ cd \path\to\openidm

$ run.bat

Start in debug mode [1] default

Start in normal mode [2]

Show help [3]

Chose a number (1-3):

Listening for transport dt_socket at address: 5005

...

-&gt;</screen>

<para>You can enter commands at the resulting <literal>-&gt;</literal> prompt

such as <literal>help</literal> for usage, or <literal>ps</literal> to view

the bundles installed. To see a list of all the OpenIDM core services

and their state enter the following (if startup was successful all states

should be active):

</para>

<screen width='100'>

-&gt; scr list

Id State Name

[ 8] [active ] embedded-orientdb-server-component

[ 0] [active ] org.forgerock.openidm.audit

[ 5] [active ] org.forgerock.openidm.provisioner.openicf.connectorinfoprovider

[ 3] [active ] org.forgerock.openidm.router

[ 12] [active ] org.forgerock.config

[ 11] [active ] org.forgerock.openidm.scheduler

[ 10] [active ] org.forgerock.openidm.restlet

[ 6] [active ] org.forgerock.openidm.provisioner.openicf

[ 7] [active ] org.forgerock.openidm.provisioner.openicf

[ 2] [active ] org.forgerock.openidm.managed

[ 9] [active ] org.forgerock.openidm.repo.orientdb

[ 4] [active ] org.forgerock.openidm.provisioner

[ 1] [active ] org.forgerock.openidm.sync

-&gt;

</screen>

</step>

<step>

<para>You may also manage the container and services from the Felix administration console. The console may be started with the following defaults:</para>

<itemizedlist>

<listitem>

<para>Console URL: <link

xlink:href='http://localhost:8080/system/console'

>http://localhost:8080/system/console</link>.</para>

</listitem>

<listitem>

<para>Username: <literal>admin</literal></para>

</listitem>

<listitem>

<para>Password: <literal>admin</literal></para>

</listitem>

</itemizedlist>

<para>

To see the OpenIDM core services and their respective states

click on the Components tab. Or select the Shell tab and

enter <literal>scr list</literal>. To restart or shutdown the container go to the

System tab.

</para>

</step>

<step>

<para>Executing the REST Interfaces</para>

<para>

The following REST command will return a json file with all users in the OpenIDM

repository. If there are alredy some users in the repository, they were created as a result of the

sample reconciliation task. If the reconciliation task has not yet run your request will return an empty set.

If sending the URL in the browser it depends on your browser settings how the result will be show.

</para>

<para>URL:

<link xlink:href="http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids" >

http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids

</link>

</para>

<para>

<para>

The same URL can be used with the curl command line tool which is part of most os. For more info see:

<link xlink:href="http://curl.haxx.se/">http://curl.haxx.se/</link>

</para>

Or create your own user joe by sending a RESTful PUT. Here is a sample curl

command to create the user joe in the repository.

</para>

<screen width='100' >

$ curl -X PUT -d '{"name":"joe","firstname":"joe","lastname":"smith","email":"joe@abc.com"}'

{"_rev":"1","_id":"joe"}

$

</screen>

<para>

Now fetch the newly created user from the repository with a RESTful GET from

the browser

<link

xlink:href="http://localhost:8080/openidm/managed/user/joe"

>http://localhost:8080/openidm/managed/user/joe</link>

or from the command line using curl.

</para>

<screen width='100' >

$ curl http://localhost:8080/openidm/managed/user/joe

{"_id":"joe","_rev":"1","email":"joe@abc.com","name":"joe","lastname":"smith","firstname":"joe"}

$

</screen>

</step>

</procedure>

<procedure>

<title>Stop the OpenIDM Services</title>

<step performance='optional'>

<para>To stop the OpenIDM services enter the shutdown command in the shell</para>

<screen width='100' >

-&gt; shutdown

...

$

</screen>

</step>

<step>

<para>Or start the Felix console

<link

xlink:href='http://localhost:8080/system/console'

>http://localhost:8080/system/console</link>

and click on the stop button under the System Information tab.

Please note this will stop the servlet container so the console

will no longer be accessible.

</para>

</step>

</procedure>

</section>

</section>

</chapter>