<?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 and start

OpenIDM.</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>

<indexterm>

<primary>Java</primary>

<secondary>Requirements</secondary>

</indexterm>

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

<para>The equivalent version of OpenJDK should work for evaluation,

too.</para>

</section>

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

<title>Application Container</title>

<indexterm>

<primary>Application container</primary>

<secondary>Requirements</secondary>

</indexterm>

<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. For OpenIDM

<?eval ${docTargetVersion}?>, the only supported configuration is running

the services in Apache Felix and Jetty.</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>

<indexterm>

<primary>Installing</primary>

</indexterm>

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

<step>

<para>Make sure you have an appropriate 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>

<para>Check the release notes for Java requirements in the chapter, <link

xlink:href="release-notes#chap-before-you-install"

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

Install OpenIDM Software</citetitle></link>.</para>

</step>

<step>

<indexterm>

<primary>Downloading</primary>

</indexterm>

<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-<?eval ${docTargetVersion}?>.zip

...

inflating: openidm/connectors/openicf-scriptedsql-connector-<?eval ${openicfBundleVersion}?>.jar

inflating: openidm/bin/felix.jar

inflating: openidm/bin/openidm.jar

$</screen>

</step>

<step performance="optional">

<para>By default, OpenIDM listens for HTTP connections on port 8080. To

change the default port, edit

<filename>openidm/conf/jetty.xml</filename>.</para>

</step>

<step performance="optional">

<indexterm>

<primary>Repository database</primary>

<secondary>Requirements</secondary>

</indexterm>

<para>Before running OpenIDM in production, replace the default 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>

<indexterm>

<primary>Starting OpenIDM</primary>

</indexterm>

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

<para>To run OpenIDM as a background process, see the chapter on <link

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

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Starting &amp;

Stopping OpenIDM</citetitle></link> in the <citetitle>Integrator's

Guide</citetitle>.</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>Start OpenIDM (UNIX).</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>Start OpenIDM (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>

<indexterm>

<primary>Getting started</primary>

</indexterm>

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

repository. To access the OpenIDM repository over REST, you can use a

browser-based REST client, such as the

<link xlink:href="https://chrome.google.com/webstore/detail/simple-rest-client/fhjcajmcbmldlhcimfajhfbgofnpcjmb">

Simple REST Client</link> for Chrome, or <link xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/">

RESTClient</link> for Firefox. Alternatively you can use the

<command>curl</command> command-line tool that is included with most

operating systems. For more information on <command>curl</command>, see

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

you cannot locate the <command>curl</command> command on your system, you

can download it from

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

</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/?_queryId=query-all-ids</screen>

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

exist.</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>Create <literal>joe</literal> (UNIX).</para>

<screen>$ curl

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

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

--request PUT

--data '{

"userName":"joe",

"givenName":"joe",

"familyName":"smith",

"email":["joe@example.com"],

"description":"My first user"

}'

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

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

</step>

<step>

<para>Create <literal>joe</literal> (Windows).</para>

<screen>C:\&gt;curl

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

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

--request PUT

--data "{

\"userName\":\"joe\",

\"givenName\":\"joe\",

\"familyName\":\"smith\",

\"email\":[\"joe@example.com\"],

\"description\":\"My first user\"

}"

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

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

</step>

</stepalternatives>

</step>

<step>

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

GET.</para>

<screen>$ curl

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

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

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

{

"familyName": "smith",

"userName": "joe",

"givenName": "joe",

"_id": "joe",

"_rev": "0",

"email": [ "joe@example.com" ],

"description": "My first user"

}</screen>

<para>The JSON output shown above is formatted for easier reading. OpenIDM

returns the JSON object all on one line.</para>

</step>

</procedure>

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

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

<indexterm>

<primary>Stopping OpenIDM</primary>

</indexterm>

<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>