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

<itemizedlist>

<para>Download OpenIDM from one of the following locations:</para>

<listitem>

<para>

<link xlink:show="new" xlink:href="http://www.forgerock.com/download-stack/">

Enterprise Downloads</link> has the latest stable, supported

release of OpenIDM and the other products in the ForgeRock

identity stack.</para>

</listitem>

<listitem>

<para><link xlink:show="new" xlink:href="http://forgerock.org/openidm.html">

Builds</link> includes the nightly build, the nightly experimental

build, and the OpenIDM agents. Note that this is the working

version of the trunk and should not be used in a production

environment.</para>

</listitem>

<listitem>

<para>

<link xlink:show="new" xlink:href="http://forgerock.org/openidm-archive.html">

Archives</link> includes the stable builds for all previous releases

of OpenIDM.</para>

</listitem>

</itemizedlist>

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

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

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

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

OpenIDM version "2.1.0-SNAPSHOT" (revision: 1660)

-> OpenIDM ready</screen>

</step>

<step>

<para>Start OpenIDM (Windows).</para>

<screen>&lt; cd \path\to\openidm

&lt; startup.bat

"Using OPENIDM_HOME: \path\to\openidm"

"Using OPENIDM_OPTS: -Xmx1024m -Dfile.encoding=UTF-8"

"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

OpenIDM version "2.1.0-SNAPSHOT" (revision: 1660)

-> OpenIDM ready

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

scr list

Id State Name

Id State Name

[ 27] [active ] org.forgerock.openidm.endpoint

...

[ 18] [unsatisfied ] org.forgerock.openidm.info

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

[ 31] [active ] org.forgerock.openidm.ui.simple

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

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

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

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

[ 33] [unsatisfied ] org.forgerock.openidm.schedule

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

[ 32] [active ] org.forgerock.openidm.workflow

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

[ 28] [unsatisfied ] org.forgerock.openidm.provisioner.openicf

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

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

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

[ 35] [active ] org.forgerock.openidm.taskscanner

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

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

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

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

[ 11] [unsatisfied ] org.forgerock.openidm.sync

[ 20] [active ] org.forgerock.openidm.policy

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

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

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

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

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

[ 30] [unsatisfied ] org.forgerock.openidm.servletfilter

[ 19] [active ] org.forgerock.openidm.infoservice

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

-&gt;</screen>

<para>A default startup does not include certain configurable services,

which will indicate an <literal>unsatisfied</literal> state until they

are included in the configuration. As you work through the sample

configurations described later in this guide, you will notice that these

services are active.</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 utility 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",

"phoneNumber":"555-123-1234",

"password":"TestPassw0rd",

"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\",

\"phoneNumber\":\"555-123-1234\",

\"password\":\"TestPassw0rd\",

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

{

"stateProvince": "",

"userName": "joe",

"roles": "openidm-authorized",

"givenName": "joe",

"address2": "",

"lastPasswordAttempt": "Wed Nov 28 2012 22:19:35 GMT+0200 (SAST)",

"address1": "",

"familyName": "smith",

"passwordAttempts": "0",

"_rev": "0",

"_id": "joe",

"country": "",

"city": "",

"lastPasswordSet": "",

"postalCode": "",

"phoneNumber": "555-123-1234",

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

"description": "My first user",

"accountStatus": "active"

}</screen>

<para>OpenIDM returns the JSON object all on one line. To format the JSON

for legibility, use a JSON parser, such as <link

xlink:href="http://stedolan.github.com/jq/">jq</link>.</para>

<para>Notice that more attributes are returned for user <literal>joe</literal>

than the attributes you added in the previous step. The additional

attributes are added by a script named

<literal>onCreate-user-set-default-fields.js</literal> that is triggered

whan a new user is created. For more information, see <link

xlink:href="integrators-guide#managed-object-configuration"

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

Configuration</citetitle></link> in the <citetitle>Integrator's Guide</citetitle>.

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