[=#topofpage]

''Responsible for this page: [wiki:mwindhouwer Menzo Windhouwer].''
''Last content check: 28-08-2012''

{{{
#!html
<h3>Purpose</h3>
}}}

The purpose of this page is to collect relevant information about ISOcat.


= Project: ISOcat =

ISOcat is an implementation of ISO 12620:2009, which describes the data model and procedures around a Data Category Registry (DCR).

----
== Contents ==

[[PageOutline(1-2, , inline)]]


----
== People ==

 * [[mwindhouwer|Menzo Windhouwer]]
 * ([[andmor|André Moreira]])

----
== Getting code ==

 * You can browse the code [source:cats here]
 * Check out from: {{{https://svn.clarin.eu/cats/ISOcat}}}

----
== System Requirements ==

 * [[http://java.oracle.com/|Java 6]]
 * [[http://ant.apache.org/|Apache Ant]]
 * [[http://download.netkernel.org/nkse/|1060 NetKernel 3.3.1 Standard Edition Development Kit]] (with some additional patches included in our codebase)
 * [[http://www.postgresql.org/|PostgreSQL 8.x]] (an external instance uses 9.x)
 * [[http://www.generalinterface.org/|General Interface 3.9.1]]
 * [[http://tango.freedesktop.org/Tango_Icon_Library|Tango icon library]] (to be phased out, but still some leftovers)
 * [[http://www.famfamfam.com/lab/icons/silk/|famfamfam silk icon library]] and [[http://damieng.com/creative/icons/silk-companion-1-icons|silk companion]]
 * [[http://code.google.com/p/mimeparse/|mimeparse JavaScript library]]
 * [[http://ostermiller.org/utils/|Ostermiller Java Utilities]]
 * the ISOcat forum is based on [[http://www.phpbb.com/|phpBB]] (with some additional patches included in our codebase)

----
== Dependencies ==

There are several other CLARIN projects that make use of data categories and use the ISOcat REST API:

 * [[ComponentRegistryAndEditor|CMDI component registry and editor]]
 * [[MetadataEditor|Arbil]] (for CMDI)

There are also companion registries under development:

 * RELcat, a [[RelationRegistry|Relation Registry]]
 * SCHEMAcat, a [[SchemaCat|Schema Registry]]

----
== Building and Deploying ==

 ''!NetKernel''
 * download and install [[http://download.netkernel.org/nkse/|1060 NetKernel 3.3.1 Standard Edition Development Kit]]
 * start !NetKernel using the appropiate startup script in {{{path-to-1060-NKSEDK-3.3.1/bin}}}
 * goto [[http://localhost:1060]]
 * goto the ''Module Management Wizard'' in the ''control panel'' and update all existing modules
   * at time of writing this will update the HTTP Client Services, the HTTP Transport and XQuery
 * shutdown !NetKernel (''Kernel Shutdown'' in the ''control panel'') 

 ''Patch !NetKernel''
 * checkout our precompiled !NetKernel patches from [[source:cats/patches/NetKernel/trunk/dist]]
 * and copy these files in the equivalent places in your !NetKernel installation directory
 * remove all jars from {{{path-to-1060-NKSEDK-3.3.1/lib/expanded}}}, so the libraries our patched modules use will be unpacked with a next restart

 ''3rd party !NetKernel modules''
 * checkout some 3rd party !NetKernel modules from [[source:cats/patches/NetKernel/trunk/contrib]]
 * copy these jars into {{{path-to-1060-NKSEDK-3.3.1/modules}}}
 * add the following to the end (before {{{</modules>}}}) of {{{path-to-1060-NKSEDK-3.3.1/etc/deployedModules.xml}}} to enable these modules
   {{{
<module>modules/mod-e4x-1.0.0.jar</module>
<module>modules/db-metadata.jar</module>
<module>modules/mod-stink-0.1.0.jar</module>
<module>modules/test-stink-0.1.0.jar</module>
   }}}

 ''SLOOT !NetKernel module''
 * checkout the SLOOT !NetKernel modules, which is an in-house developed module with generic !NetKernel tools, from [[source:cats/shared]] into an own folder
 * download the [[http://code.google.com/p/mimeparse/|mimeparse JavaScript library]]
 * create a {{{local-props.xml}}} file in the SLOOT folder specifying the location of !NetKernel and mimeparse
   {{{
<project name="local-props" basedir=".">
        <!-- local 1060 NK directory -->
        <property name="nk" location="/path-to-1060-NKSEDK-3.3.1/"/>

        <!-- external library directories -->
        <property name="mimeparse" location="/path-to-mimeparse"/>
</project>
   }}}
 * rename the old {{{ext-xquery-2.4.3.jar}}} module in {{{path-to-1060-NKSEDK-3.3.1/modules}}} to {{{ext-xquery-2.4.3.jar.BAK}}} to prevent some clashes
 * run {{{ant}}} in the top SLOOT folder
 * add the following (adapt the path to point to your ISOcat source directory) to the end (before {{{</modules>}}}) of {{{path-to-1060-NKSEDK-3.3.1/etc/deployedModules.xml}}} to enable this module
   {{{
<module>/path-to-SLOOT/mod-SLOOT</module>
   }}}

 ''ISOcat development-only !NetKernel modules''
 * checkout the ISOcat !NetKernel modules from [[source:cats/ISOcat/trunk]] in your ISOcat source code folder
 * the modules in the {{{path-to-ISOcat/develop}}} are !NetKernel modules to serve static files that in a production environment will be served by the HTTP server, e.g., Apache
 * some of these static files need to be downloaded and placed in the right directory
   * download the [[http://www.generalinterface.org/|General Interface 3.9.1]] Debug edition (in a production environment use the Standard edition) and place the content of the archive into the {{{path-to-ISOcat/develop/mod-gi/gi/3_9_1/}}} directory (notice the underscores)
   * download the [[http://tango.freedesktop.org/Tango_Icon_Library|Tango icon library]] {{{tango-icon-theme}}} and place the content of the archive into the {{{path-to-ISOcat/develop/mod-Tango/Tango/}}} directory (in a production environment ISOcat only needs the {{{16x16}}} subdirectory)
   * download the [[http://www.famfamfam.com/lab/icons/silk/|famfamfam silk icon library]] and place the content of the archive into the {{{path-to-ISOcat/develop/mod-famfamfam/famfamfam/silk}}} directory
   * download the [[http://damieng.com/creative/icons/silk-companion-1-icons|silk companion]] and place the content of the archive into the {{{path-to-ISOcat/develop/mod-famfamfam/famfamfam/silk-companion}}} directory (there are several other ''silk companion'' icon sets, which might be interesting for new developments)
 * add the following (adapt the path to point to your ISOcat source directory) to the end (before {{{</modules>}}}) of {{{path-to-1060-NKSEDK-3.3.1/etc/deployedModules.xml}}} to enable these modules
   {{{
<module>/path-to-ISOcat/develop/mod-gi</module>
<module>/path-to-ISOcat/develop/mod-Tango</module>
<module>/path-to-ISOcat/develop/mod-famfamfam</module>
   }}}
 * tell the !NetKernel HTTP frontend fulcrum to resolve request for the files in these modules by adding the following below the ''Add your modules below here...'' comment in {{{path-to-1060-NKSEDK-3.3.1/modules/mod-fulcrum-frontend/module.xml}}}
   {{{
<import>
  <uri>urn:gi</uri>
</import>
<import>
  <uri>urn:tango</uri>
</import>
<import>
  <uri>urn:famfamfam</uri>
</import>
   }}}

 ''ISOcat PostgreSQL database''
 * download and install [[http://www.postgresql.org/|PostgreSQL 8.x]] (or dare to try 9.x)
 * create an isocat user (password: isocat) and an isocat database
   {{{
CREATE ROLE isocat LOGIN PASSWORD 'isocat';
CREATE DATABASE isocat WITH owner = isocat ENCODING = 'UTF8';
   }}}	
 * depending on the configuration of your PostgreSQL installation the pgpsql language has to be loaded
   {{{   
CREATE PROCEDURAL LANGUAGE plpgsql;
   }}}
 * initialize an empty database (or ask for a recent dump of isocat.org)
   {{{
cat path-to-ISOcat/mod-ISOcat-access-data/dbms/ISOcat-schema-empty.sql | psql -U isocat -W isocat
cat path-to-ISOcat/mod-ISOcat-access-data/dbms/ISOcat-schema-init.sql | psql -U isocat -W isocat
cat path-to-ISOcat/mod-ISOcat-access-data/dbms/ISOcat-schema-constraints.sql | psql -U isocat -W isocat
   }}}

 ''ISOcat !NetKernel modules''
 * download the [[http://ostermiller.org/utils/|Ostermiller Java Utilities]]
 * create a {{{local-props.xml}}} file in the {{{path-to-ISOcat/mod-ISOcat-utils}}} folder specifying the location of !NetKernel and the Ostermiller Java Utilities
   {{{
<project name="props" basedir=".">
        <!-- 1060 NK directory -->
        <property name="nk" location="/path-to-1060-NKSEDK-3.3.1"/>

        <!-- external library directories -->
        <property name="ostermiller" location="/path-to-Ostermiller"/>
</project>
   }}}
 * run {{{ant}}} in the top ISOcat folder
 * add the following (adapt the path to point to your ISOcat source directory) to the end (before {{{</modules>}}}) of {{{path-to-1060-NKSEDK-3.3.1/etc/deployedModules.xml}}} to enable these modules
   {{{
<module>/path-to-ISOcat//mod-ISOcat-utils</module>
<module>/path-to-ISOcat/mod-ISOcat-documentation</module>
<module>/path-to-ISOcat/mod-ISOcat-access-data</module>
<module>/path-to-ISOcat/mod-ISOcat-access-system</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-system</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-access</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-balloting</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-user</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-group</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-dcs</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-dc</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-tdg</module>
<module>/path-to-ISOcat/mod-ISOcat-manage-dm</module>
<module>/path-to-ISOcat/mod-ISOcat-control-session</module>
<module>/path-to-ISOcat/mod-ISOcat-control-access</module>
<module>/path-to-ISOcat/mod-ISOcat-interface-gi</module>
<module>/path-to-ISOcat/mod-ISOcat-interface-rest</module>
<module>/path-to-ISOcat/mod-ISOcat-site</module>
   }}}
 * tell the !NetKernel HTTP frontend fulcrum to resolve request for the files in the interface modules by adding the following below the ''Add your modules below here...'' comment and the previously added modules in {{{path-to-1060-NKSEDK-3.3.1/modules/mod-fulcrum-frontend/module.xml}}}
   {{{
<import>
  <uri>urn:isocat:interface:rest</uri>
</import>
<import>
  <uri>urn:isocat:interface:gi</uri>
</import>
<import>
  <uri>urn:isocat:site</uri>
</import>
   }}}
 * tell the !NetKernel HTTP backend fulcrum to resolve requests for the configuration plugin by adding the following before the {{{</mapping>}}} closing tag in {{{path-to-1060-NKSEDK-3.3.1/modules/mod-fulcrum-backed/module.xml}}}
  {{{
<import>
  <uri>urn:isocat:manage:system</uri>
</import>
  }}}

 ''Configure ISOcat''
 * start !NetKernel using the appropiate startup script in {{{path-to-1060-NKSEDK-3.3.1/bin}}}
 * goto [[http://localhost:1060]]
 * goto the ''ISOcat system management'' section in ''applications''
 * enter a valid SMTP server in the ''Configure'' form
 * goto [[http://localhost:8080/isocat/]]

 '''Note''':  There is currently a concurrency problem in the class loader which can lead to multiple Saxon Configuations, which should be a Singleton. Check for any 'Externally supplied NodeInfo belongs to the wrong Configuration' messages during startup or a first access. If this happens restart the server and check again ... the concurrency bug doesn't happen that often.

 ''Finetuning''

 The cron jobs generate some superfluous logging messages, which can be switched off

 * goto [[http://localhost:1060]]
 * goto the ''Configuring Logging Levels'' section in the ''control panel''
 * select the ''Cron'' log
 * allow only warnings and severe errors
 * save your changes

 ''Developing the General Interface frontend''

 The GI Builder application basically only runs on Internet Explorer. If your primary OS isn't Windows you'll have to install one in a VM. In general you can get access to your ISOcat codebase using some form of shared folders. If not you need a checkout of the [[source:cats/ISOcat/trunk/mod-ISOcat-interface-gi]] !NetKernel module and the [[http://www.generalinterface.org/|General Interface 3.9.1]] Debug edition. The frontend codebase in mod-ISOcat-interface-gi uses {{{http://isocat/}}} as the base for the application. In the Windows VM you'll have to map this to the host machines IP address. Add the mapping {{{your-ip-address     isocat}}} to {{{C:\Windows\System32\drivers\etc\hosts}}} (you'll need administrator access to change this file).

 '''Note''': You'll need to update the Windows {{{hosts}}} file anytime your IP address changes. Also when your machine is offline and you don't have an IP address GI Builder won't have a way to reach the ISOcat backend. (If you find a solution to develop the UI offline please add the trick to this page!)

 '''Note''': If Windows is your primary OS you'll still needs to map {{{localhost}}} to {{{isocat}}} in the hosts file to let GI Builder contact the ISOcat backend. 

----
== Interfaces ==

There is a [http://www.isocat.org/rest/help.html public readonly REST API] and the [http://www.isocat.org/interface/ General Interface web UI].

----
== Manual ==

See [http://www.isocat.org/manual/ the manual page at isocat.org]

----
== Design ==


----
== Tickets ==

[[TicketQuery(status=accepted|assigned|new|reopened,component=ISOcat,order=priority,format=table,col=summary|version|type|priority|owner|reporter)]]

There is also a public [https://sourceforge.net/tracker/?group_id=244572 bug and issue tracker] at !SourceForge.

----
== Servers ==

The ISOcat production server is [[http://www.isocat.org/|www.isocat.org]].

The ISOcat test server is [[http://lux13.mpi.nl/|lux13]], which also hosts alpha versions of RELcat and SCHEMAcat.

----
== Status, Planning and Roadmap ==

Status: active

Planning and roadmap: 

----
== History ==