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

<chapter xml:id='chap-install'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

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

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

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

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

<title>Installing OpenIDM Services</title>

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

<section xml:id="before-you-start">

<title>Before You Run OpenIDM</title>

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

</para>

<section xml:id="java-prerequisites">

<title>Java Environment</title>

<para>OpenIDM requires Oracle Java SE JDK 6 update 24 or later.</para>

<!-- TODO: When this doc has been reviewed, either the next sentence should

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

</section>

<section xml:id="application-container-prerequisites">

<title>Application Container</title>

<para>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 default Servlet container is Jetty. The default noSQL

database is OrientDB. At this time the only supported configuration is

running the services in Apache Felix.</para>

</section>

</section>

<section xml:id="installing-openidm">

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

<para>Follow the procedures in this section to install and run

OpenIDM.</para>

<procedure xml:id="install-openidm">

<title>To Install OpenIDM Services</title>

<para>Follow these steps to install OpenIDM.</para>

<step>

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

<screen>$ 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'>download page</link>.</para>

</step>

<step>

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

<screen>$ 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 listens on port 8080. To

change the default port, edit the

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

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

</step>

<step>

<para>Before running OpenIDM in production, replace the OrientDB

repository provided for evaluation with a JDBC repository.</para>

<para>See the chapter on <link xlink:href="install-guide#chap-repository"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Installing

a Repository For Production</citetitle></link> for details.</para>

</step>

</procedure>

<procedure xml:id="run-openidm">

<title>To Start OpenIDM Services</title>

<para>Follow these steps to run OpenIDM.</para>

<step>

<para>Start the Felix container, load all OpenIDM services, and start a

command shell to allow you to manage the container.</para>

<stepalternatives>

<step>

<para>On UNIX, Linux, and Mac OS X</para>

<screen>$ /startup.sh

Using OPENIDM_HOME: /path/to/openidm

Using OPENIDM_OPTS: -Xmx1024m

Using LOGGING_CONFIG:

-Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties

Using boot properties at /path/to/openidm/conf/boot/boot.properties

-&gt;</screen>

</step>

<step>

<para>On Windows</para>

<screen>$ cd \path\to\openidm

$ startup.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>

</step>

</stepalternatives>

<para>At the resulting <literal>-&gt;</literal> prompt, you can enter

commands such as <command>help</command> for usage, or

<command>ps</command> to view the bundles installed. To see a list of all

the OpenIDM core services and their states, enter the following

command.</para>

<screen>-&gt; scr list

Id State Name

[ 16] [active ] org.forgerock.openidm.config.starter

[ 7] [active ] org.forgerock.openidm.external.rest

[ 11] [active ]

org.forgerock.openidm.provisioner.openicf.connectorinfoprovider

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

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

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

[ 6] [unsatisfied ] org.forgerock.openidm.external.email

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

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

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

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

[ 9] [active ] org.forgerock.openidm.http.contextregistrator

[ 17] [active ] org.forgerock.openidm.config

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

[ 14] [unsatisfied ] org.forgerock.openidm.repo.jdbc

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

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

[ 8] [active ] org.forgerock.openidm.authentication

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

-&gt;</screen>

<para>If startup was successful, all states except <literal>email</literal>

and <literal>repo.jdbc</literal> are active. If any other services remain

<literal>unsatisfied</literal>, check <filename>openidm/logs</filename>

for errors, and refer to the chapter on <link

xlink:href="integrators-guide#chap-troubleshooting"

xlink:role="http://docbook.org/xlink/role/olink"

><citetitle>Troubleshooting</citetitle></link> in the

<citetitle>Integrator's Guide</citetitle>.</para>

</step>

<step>

<para>Alternatively, you can manage the container and services from the

Felix administration console.</para>

<itemizedlist>

<para>Use these hints to connect to the console.</para>

<listitem>

<para>Default Console URL: <link xlink:show="new"

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

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

</listitem>

<listitem>

<para>Default user name: <literal>admin</literal></para>

</listitem>

<listitem>

<para>Default password: <literal>admin</literal></para>

</listitem>

</itemizedlist>

<itemizedlist>

<para>Some basic hints on using the Felix administration console

follow.</para>

<listitem>

<para>Select the Components tab to see OpenIDM core services and their

respective states.</para>

</listitem>

<listitem>

<para>Select the Shell tab to access the <literal>-&gt;</literal>

prompt.</para>

</listitem>

<listitem>

<para>Select the System Information tab to stop or restart the

container.</para>

</listitem>

</itemizedlist>

</step>

</procedure>

<procedure xml:id="first-steps-with-rest">

<title>To Get Started With the OpenIDM REST Interface</title>

<para>OpenIDM provides RESTful access to users in the OpenIDM

repository.</para>

<step>

<para>Access the following URL to get a JSON file including all users in

the OpenIDM repository.</para>

<screen>$ curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

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

<para>When you first install OpenIDM with an empty repository, no users

exist.</para>

<para>The <command>curl</command> command line tool is included with most

operating systems.<footnote><para>For more

information on <command>curl</command>, see <link

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

</footnote></para>

</step>

<step>

<para>Create a user <literal>joe</literal> by sending a RESTful PUT.</para>

<para>The following <command>curl</command> commands create the user

<literal>joe</literal> in the repository.</para>

<stepalternatives>

<step>

<para>On UNIX, Linux, and Mac OS X</para>

<screen>$ curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

--request PUT

--data '{

"name":"joe",

"firstname":"joe",

"lastname":"smith",

"email":"joe@abc.com",

"userPassword":"11111111"

}'

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

{"_rev":"0","_id":"joe"}</screen>

</step>

<step>

<para>On Windows</para>

<screen>C:\&gt;curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

--request PUT

--data {

\"name\":\"joe\",

\"firstname\":\"joe\",

\"lastname\":\"smith\",

\"email\":\"joe@abc.com\",

\"userPassword\":\"11111111\"

}

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

{"_rev":"0","_id":"joe"}</screen>

</step>

</stepalternatives>

</step>

<step>

<para>Fetch the newly created user from the repository with a RESTful

GET.</para>

<stepalternatives>

<step>

<para>Browse to <link xlink:show="new"

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

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

</step>

<step>

<para>Use the <command>curl</command> command.</para>

<screen>$ curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

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

{

"lastname":"smith",

"userpassword":"11111111",

"firstname":"joe",

"_id":"joe",

"_rev":"0",

"email":"joe@abc.com",

"name":"joe"

}</screen>

</step>

</stepalternatives>

</step>

</procedure>

<procedure xml:id="stop-openidm">

<title>To Stop the OpenIDM Services</title>

<step>

<para>You can stop OpenIDM Services from the <literal>-&gt;</literal>

prompt, or through the Felix console.</para>

<stepalternatives>

<step>

<para>Either enter the <command>shutdown</command> command at the

<literal>-&gt;</literal> prompt.</para>

<screen>-&gt; shutdown

...

$</screen>

</step>

<step>

<para>Or click Stop on the System Information tab of the Felix console,

by default <link xlink:show="new"

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

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

<para>This stops the Servlet container as well, and the console is

no longer accessible.</para>

</step>

</stepalternatives>

</step>

</procedure>

</section>

</chapter>