Difference between revisions of "ART installation manual"
(One intermediate revision by one other user not shown) | |||
Line 1: | Line 1: | ||
+ | {{SeeNewDocs}} | ||
{{2019_svn_to_git_issuebox}} | {{2019_svn_to_git_issuebox}} | ||
==Project hosting == | ==Project hosting == | ||
− | {{ | + | {{NoteBox|We offer free project hosting on ART-DECOR. Feel free to [[contact]] us if you are interested.}} |
==Introduction== | ==Introduction== |
Latest revision as of 19:48, 9 November 2022
This is documentation for ART-DECOR Release 2 and tends to be out-dated. Please visit our new documentation site at docs.art-decor.org
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. |
Contents
- 1 Project hosting
- 2 Introduction
- 3 Prerequisites
- 4 Download and install Apache Tomcat
- 5 Download and install ART-DECOR Orbeon web archive
- 6 Download and install the ART-DECOR eXist-db server
- 7 Install ART-DECOR software & data
- 8 Load OIDIndex data
- 9 Update tomcat and the ART-DECOR orbeon web archive
- 10 Update only the ART-DECOR orbeon web archive
- 11 Update ART-DECOR software & data
- 12 Update ART-DECOR configuration
- 13 Upgrade eXist-db
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:
2.
Click on the ‘Not logged in’ and log in as admin with the password you entered during installation.
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
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.
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:
- http://decor.nictiz.nl/apps/public-repo/retrieve.html (Stable release)
- http://decor.nictiz.nl/apps/public-repo-dev/retrieve.html (Development release)
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:
6.
Select ‘available’ to show the packages available in the repository. Hovering over a package will show the install icon:
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:
- Advanced Requirements Tooling
- This is the core application package.
- DECOR core files
- Contains Decor schema, xslt and other core resources.
- DECOR services
- Contains the modules for the Decor REST services.
- ART-DECOR System Services
- Contains resources related to ART-DECOR system services like ADANS (automatic notifier system) and ADRAM (release and release manager).
- Terminology Applications
- Contains the terminology applications and services.
- XIS Test information system (optional)
- Contains applications for testing of HL7 messages and messaging services.
- 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:
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:
- for MAC OS X: ART installation manual#Download and install Apache Tomcat
- for linux: ART-DECOR installation on linux#Apache Tomcat installation
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:
- create a backup of the existing tomcat and art-decor.war configuration.
- download a new version: see ART installation orbeon
- save it by overwriting the existing .war
- stop and start tomcat
- edit ART-DECOR Orbeon configuration:
- for MAC OS X, see ART installation orbeon
- or for linux, see ART-DECOR installation on linux#Edit ART-DECOR Orbeon configuration
Update ART-DECOR software & data
For running updates for ART-DECOR software, the following process can be performed:
- See Release channels (stable) for release notes per package update for stable software.
- Follow steps 1 to 6 from Install ART-DECOR software and data
- Check if there are package updates available for your installation:
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:
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:
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.
- Check ART maintenance manual#ART_Server_Settings for details
- 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