ART installation manual

Revision as of 10:07, 14 March 2019 by Mligtvoet (talk | contribs)
Information.svg Only applies to users that use code directly from our subversion repository: Please note we are in the process of moving from sourceforge subversion to git at: https://bitbucket.org/art-decor/art-decor/

For now in the testing phase, once this is final we will update links in the documentation.

Project hosting

We offer free project hosting on ART-DECOR. Feel free to contact us if you are interested.

Introduction

This page contains a short overview of the installation process. For a more complete installation manual for ART-DECOR in production environments, see ART-DECOR installation on linux.

Prerequisites

The software requires a Java development environment (JDK).

Download and install Apache Tomcat

Download and install Apache Tomcat following the instructions for your platform.

Installation on OS X

Download a binary distribution of the core module: apache-tomcat-7.x.y.tar.gz (where x.y should be replaced with the latest stable release of Tomcat. In examples below Tomcat version 7.0.0 is used).

Opening/unarchiving the archive will create a folder structure something like this in your Downloads folder:

~/Downloads/apache-tomcat-7.0.0/apache-tomcat-7.0.0

Move the unarchived distribution to /usr/local:

sudo mv ~/Downloads/apache-tomcat-7.0.0/apache-tomcat-7.0.0 /usr/local

To make it easy to replace this release with future releases, we are going to create a symbolic link that we are going to use when referring to Tomcat:

sudo ln -s /usr/local/apache-tomcat-7.0.0 /Library/Tomcat

Change ownership of the /Libaray/Tomcat folder hierarchy:

sudo chown -R <your_username> /Library/Tomcat

Make all scripts executable:

sudo chmod +x /Library/Tomcat/bin/*.sh

Instead of using the start and stop scripts, you may also want to check out Activata’s Tomcat Controller a tiny freeware app, providing a UI to quickly start/stop Tomcat.

Download and install ART-DECOR Orbeon web archive

Download the art-decor.war file from: http://sourceforge.net/projects/artdecor/files/Orbeon/art-decor.war/download

Unzip.

Follow the instructions in the readme file: http://sourceforge.net/projects/artdecor/files/Orbeon/README.txt/download

Download and install the ART-DECOR eXist-db server

1.

Download the eXist-db installer file from: http://sourceforge.net/projects/artdecor/files/eXist-db/eXist-db-setup-2.1-rev0000.jar/download Note: this is an installer with specific configuration prepared for ART-DECOR.

2.

Start the installer by double clicking on the installation file. Follow the instructions in the installer, keep clicking ‘next’ until the installation process is completed. Note: enter an admin password when asked, do not leave it blank. Note 2: When the LOINC or Snomed-CT or any of the larger terminology packages will be installed on the server, setting the memory amount to 4096 mb or higher is recommended.

3.

Start the eXist-db server. How to start the server is explained on the last page of the eXist-db installer.

Install ART-DECOR software & data

All ART-DECOR software and data is installed using the eXist-db package manager. The default repository URL points to the eXist-db public repository, this needs to be changed to point to the public repository residing at repository.art-decor.org.

1.

Point your browser to: http://localhost:8877/apps/dashboard/index.html You should see the dashboard page:

Error creating thumbnail: Unable to save thumbnail to destination

2.

Click on the ‘Not logged in’ and log in as admin with the password you entered during installation.

Error creating thumbnail: Unable to save thumbnail to destination

  3.

To change the default repository URL click on the ‘Collections’ icon to open the collections browser and locate the dashboard configuration at: /db/apps/dashboard

Error creating thumbnail: Unable to save thumbnail to destination

4.

Double click on the file configuration.xml to open it in eXide.

  • To install the stable release (latest version):

Change the content of the repository element to:

https://repository.art-decor.org/stable2

Save the changes.

Error creating thumbnail: Unable to save thumbnail to destination

Optionally: You can also download and install the packages from our repositories locally, although this is normally not a required step. You may find these XAR repositories at:

5.

Close the eXide editor window and click on the ‘Package Manager’ icon to open the package manager. In the default view all packages are shown, the ones that are already installed and all packages available in the repository. Selecting ‘installed’ shows the packages installed during the eXist-db installation:

Error creating thumbnail: Unable to save thumbnail to destination

6.

Select ‘available’ to show the packages available in the repository. Hovering over a package will show the install icon:

Error creating thumbnail: Unable to save thumbnail to destination

Clicking on the install icon will install the package in the database and remove it from this view.

7.

Install the application packages in the following order:

  1. Advanced Requirements Tooling
    This is the core application package.
  2. DECOR core files
    Contains Decor schema, xslt and other core resources.
  3. DECOR services
    Contains the modules for the Decor REST services.
  4. ART-DECOR System Services
    Contains resources related to ART-DECOR system services like ADANS (automatic notifier system) and ADRAM (release and release manager).
  5. Terminology Applications
    Contains the terminology applications and services.
  6. XIS Test information system (optional)
    Contains applications for testing of HL7 messages and messaging services.
  7. OID Registry tools (optional)
    Application for maintaining an OID registry, only install if you really need to maintain an OID registry.

8.

Install data packages (all optional). Click on ‘show details’ to view the Name (URI) part for all packages:

Error creating thumbnail: Unable to save thumbnail to destination

There are several types of data packages available:

  • DECOR example files

Decor example project files and associated resources.

  • Terminology data packages

These packages have: Name (URI): http://art-decor.org/ns/terminology-data/<name>

Terminology data for use by the terminology explorers and ART terminology functions (terminology associations, creating value sets).

  • Terminology Data - SNOMED CT Data

Package for creating and maintaining SNOMED CT reference sets. Please note that the full terminology package SNOMED CT data is not supplied from our repository, due to licensing issues. We do supply an empty stub package Terminology Data - SNOMED CT version 14.1.1, but this essentially contains no SNOMED CT, but just serves as an example on how to host this content.

  • HL7 XML packages

These packages have: Name (URI): http://art-decor.org/ns/hl7/<name> These packages are named: HL7 - <name> XML packages for message validation and generation.

  • Other packages

Click on ‘show details’ to view a description of the content.

9.

Start Tomcat and point your browser to: http://localhost:8080/art-decor/home

10.

Start using the ART-DECOR web application and service. You can log in as admin with the password you provided during the eXist-db installation. Read the documentation online at: documentation

Load OIDIndex data

OIDIndex data is used to provide human readable names when OIDs are used. The data for OIDIndex must be loaded when, for instance, displaying the codeSystem name for a valueset derived from SNOMED CT. If the OIDIndex data is not loaded, only the SNOMED CT OID will show, and not the displayname for the SNOMED CT codeSystem.

The following process can be performed to load data into the OIDIndex:

  • Download the data for the OIDIndex:

Export the data file hl7org-oids.xml from repository at URL: https://bitbucket.org/art-decor/art-decor-backend/src/master/utilities/hl7-oid-registry/hl7org-oids-current.xml

  • Upload the data to the eXist-db database:

Open the eXist-db dashboard, log in as admin, Collections

Click to collection: /db/apps/tools/oids-data Upload resources: select the .xml file we downloaded from the repository.

  • Convert the data to a usable format:

Open the eXist-db dashboard, eXide

Open /db/apps/tools/oids/modules/create-oid-lookupfile.xquery

Eval

This xquery will create the file: /db/apps/tools/oids-data/hl7org-lookup.xml

  • Check wether the OIDIndex works:

https://<server>/decor/services/OIDIndex

Update tomcat and the ART-DECOR orbeon web archive

Tomcat software releases are quite frequent so when updating the ART-DECOR orbeon web archive, you usually should upgrade tomcat to the latest version. Note that you should inform your users about service downtime since this step requires a tomcat stop and start. This action could take 15 to 30 minutes (depending on the speed with which you edit the ART-DECOR Orbeon configuration). For updating both tomcat and the ART-DECOR orbeon web archive art-decor.war, follow the installation procedure:

Update only the ART-DECOR orbeon web archive

Note that you should inform your users about service downtime since this step requires a tomcat stop and start. This action could take 15 to 30 minutes (depending on the speed with which you edit the ART-DECOR Orbeon configuration). For running updates for just the ART-DECOR orbeon web archive art-decor.war, the following process can be performed:

Update ART-DECOR software & data

For running updates for ART-DECOR software, the following process can be performed:

After clicking 'available' in the package manager, when package updates are available they will be shown here for example: 'Installed version: 1.3.2. Available: 1.4.0', as shown in this screenshot: En package update 01.jpg

Note that package updates are only shown if the package version numbers are updated (by the ART-DECOR expert team).

  • If package updates are available, update them by clicking Install in the following order:
    • Advanced Requirements Tooling (if update is available)
    • Terminology Applications (if update is available)
    • And continue with all packages for which updates are available

Installing an update is shown in this screenshot: En package update 02.jpg

Notes (which do not apply to the normal update process for the stable release):

  • If the process above fails and does not show package update for your installation, but you want to override and install the latest software you can always deinstall packages and reinstall the latest version.
  • If you want to switch from the stable release to a development release for packages, see step 4 from Install ART-DECOR software and data. Afterwards install the updates as usual.
  • If you want to switch from the development release to stable release, in most cases you have to deinstall the development versions for packages. Then see step 4 from Install ART-DECOR software and data. Afterwards install the updates as usual.

Update ART-DECOR configuration

  • Log into ART-DECOR. If you run it locally you probably have it running on http://localhost:8080/art-decor, otherwise you go [host]/art-decor
  • Go to Configuration > Server settings and check at least the ART server prefix and ART services prefix to see if they match your server hostname/portname.
  • Go to Configuration > Users
    • For editing DECOR projects you need at least one user with decor-admin privileges, and unless you run a local instance for yourself also one or more users with editor privileges.
    • Check ART maintenance manual#ART_users for details

Upgrade eXist-db

See Upgrade exist-db