Installing Ambra and services on single machine

See also:

Configuration Summary

Ports required:

init start-pristop-priport ssl shutdown-port
ecqs 91 15 ---- 7443 7005
mulgara 92 14 1099
random 		---- 6789
fedora 93 13 9090 9443 9005
ambra 96 10 8080
8009
random (echache) 		10443 8005
mysql -- -- 3306 ---- ----
postgresql-- -- 5432 ---- ----

ehcache is set to do peer discovery via multicast at 230.0.0.1 port 4446. If you are running multiple installations on the same network, you'll want to firewall multicast traffic appropriately to avoid cache pollution, or edit ehcache.xml and specify different multicast IP addresses for different installations. If you firewall multicast traffic, then you'll probably need to add a route for it so it gets routed via the loopback interface: 

route add -net 224.0.0.0/4 lo

Assumptions:

  • Java SDK 1.5 or higher is installed.
  • Remove all other Java packages (all gcc-java and gcj related packages)
  • Edit /etc/sysconfig/topaz-common 
    [[ -z "$JAVA_HOME" ]] && export JAVA_HOME=/path/to/java
  • PATH starts with $JAVA_HOME/bin (no other JDE or JDK is in the path)

Important Directories:

  • /etc/topaz - Configuration files
  • /usr/local/topaz/ - Binaries
    • /usr/local/topaz/bin
      • genkey stores
      • multicast
      • tomcat
  • /var/log/topaz - Log files
  • /var/lib/topaz/data - Default Mulgara and Fedora storage files
  • /var/spool/ambra - Ingest files
  • /var/cache/ambra - Cache files

Terms:

Common Tools

  • Install tools rpms 
    rpm -ivh ambra-tools-${version}.noarch.rpm
  • Generate a single certificate for use by all applications 
    /usr/local/topaz/bin/gen_keystores
 Hostname> [FQHN]
 <RETURN;
cp /tmp/keystore.[FQHN].jks /etc/topaz/keystore.jks
  • A fun and educational way to examine your keys: 
    keytool -list -keystore keystore.jks -storepass changeit | more

non standard utilities

  • (A) Install the appropriate rpm for ImageMagick? version 6.2.6
  • (B) Determine the full path to ImageMagick?'s convert utility.
  • (C) Choose a temporary directory where ImageMagick? may create files.
  • (D) Open file /etc/topaz/ambra.xml and you should see the following elements: 
    <utilities>
  <image-magick>
    <executable-path>/usr/bin/convert</executable-path>
    <temp-directory>/tmp</temp-directory>
  </image-magick>
</utilities>
  • (E) Ensure that the answer from step (B) agrees with the content of element executable-path.
  • (F) Ensure that the answer from step (C) agrees with the content of element temp-directory.

Mulgara Server

Install Mulgara

  • Install Mulgara rpms 
    rpm -ivh topaz-mulgara-${version}.noarch.rpm
  • Start Mulgara 
    service topaz-mulgara start

Fedora Server

Install MySQL

  • Install MySQL server from Yum (yum install mysql-server)
  • Set MySQL to use innodb, not isam tables. Editing /etc/my.cnf 
    [mysqld]
...
    default-storage-engine=INNODB

Install Fedora

  • Install Fedora rpms 
    rpm -ivh topaz-fedora-${version}.noarch.rpm
  • Initialize MySQL
    • Insure that you are in a writable directory, tmp files may be created
    • If prompted for a password, press <Return>, i.e. blank password
    • Insure that MySQL is up 
      service mysqld status
      • If it is necessary to start MySQL 
        service mysqld start
    • Use configuration script (Note: the user executing the script should have write privileges for the current working directory) 
      /usr/local/topaz/topaz-fedora/server/bin/mysql-config.sh [mysql_home] [mysql_dba_user] [mysql_dba_pass] [fedoradba_user] [fedora_dba_pass] [mysql_db_name] [mysql41_flag]
# arg 1 - the location where MySQL is installed (e.g., /usr/local/mysql, or /usr for a centos RPM install of mysql-server)
# arg 2 - the name of the MySQL user with dba privileges (e.g., root)
# arg 3 - the password for the MySQL user with dba privileges (use "" to indicate no password)
# arg 4 - fedoraAdmin
# arg 5 - fedoraAdmin
# arg 6 - fedora21
# arg 7 - y
  • Initialize Fedora (start and stop) 
    service topaz-fedora start
--- wait ---
service topaz-fedora stop
  • Start Fedora 
    service topaz-fedora start

CAS Server

Install PostgreSQL

  • Install pgsql server with Yum (yum install postgresql-server)

  • Start up postgresql to initialize database and config files
  • Edit /var/lib/pgsql/data/postgresql.conf: 
    tcpip_socket = true
  • Set /var/lib/pgsql/data/pg_hba.conf to: (order is important) 
    # TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
host    all         all         127.0.0.1         255.255.255.255   md5
local   all         all                                             md5
local   all         all                                             ident   sameuser
  • Create a user 
    su postgres -c 'createuser --createdb --pwprompt --encrypted USERNAME'
password = 'PASSWORD'
  • Create the database 
    su postgres -c 'createdb --owner=USERNAME casdb'
  • Update runlevel 
    chkconfig --level 345 postgresql on

Install CAS

  • Install CAS rpm 
    rpm -ivh ambra-cas-${version}.noarch.rpm
  • Edit /etc/topaz/cas.xml and set the following values:
    • config.network.hosts.cas - Change from localhost to your FQHN
    • config.network.hosts.default - Change from localhost to your FQHN (it is the name of the webhead or ambra)
    • config.cas.db.user - USERNAME
    • config.cas.db.password - PASSWORD
    • config.cas.db.url - jdbc:postgresql://localhost/casdb
  • Start CAS 
    service ambra-cas start

Ambra

Ambra Install

  • Install Ambra rpm
    • there should be no need to "force" the installation as common confg files, e.g. /etc/topaz/ambra.xml, have been re-packaged 
      rpm -ivh ambra-${version}.noarch.rpm
  • Set hosts.default in /etc/topaz/ambra.xml to FQHN
  • Configure doi-resolver /etc/topaz/ config file if necessary
  • Initialize Ambra (IMPORTANT: To create Mulgara models) 
    service ambra start
--- wait ---
service ambra stop

  • Start Ambra 
    service ambra start
  • Check that Ambra is running - make sure port 8009 is up 
    /etc/init.d/ambra status

Webhead Installation

Note: A typical development environment does not install a full Webhead. You can just tunnel or open ports 8080 and 7443. If this is the case, skip to Post Installation instructions.

Install mod_jk

this is only necessary for Apache 2.0 and earlier. for apache 2.2, use mod_proxy_ajp

mod_jk for i386:

  • install mod_jk 
    yum --enablerepo=jpackage* install mod_jk-ap20

mod_jk for x64_86: (Download latest source from http://tomcat.apache.org/connectors-doc/) 

tar -xzvf tomcat-connectors-#.#.##-src.tgz
cd tomcat-connectors-#.#.##-src/native
./configure --with-apxs=/usr/sbin/apxs (or where ever the apxs/apxs2 is)
make
su -c 'make install'

A very simple /etc/httpd/conf.d/mod_jk.conf: 

LoadModule      jk_module modules/mod_jk.so
JkWorkersFile   /etc/httpd/conf/workers.properties
JkLogFile       logs/mod_jk.log
JkLogLevel      info

A very simple /etc/httpd/conf/workers.properties: 

worker.list=ajp13
worker.ajp13.port=8009
worker.ajp13.host={FQHN}
worker.ajp13.type=ajp13

Add to webhead vhost: 

JkMount /* ajp13
AddEncodedSlashes On
ErrorDocument 503 503.html

Exclude 503 error doc files and feed from mod_jk 

SetEnvIf Request_URI "^/503.html" no-jk
SetEnvIf Request_URI "^/images/503_hdr_logo.jpg" no-jk
SetEnvIf Request_URI "^/feed/*" no-jk

Remove port 8080 from config files.

Static files and feeds

  • Copy 503 error html files to webhead docroot

Forward 7443 to 443

  • Add the following lines to /etc/sysconfig/iptables 
    *nat
:PREROUTING ACCEPT [167:22182]
:POSTROUTING ACCEPT [1:60]
:OUTPUT ACCEPT [1:60]
-A PREROUTING -d <IP ADDR> -i eth1 -p tcp -m tcp --dport 443 -j DNAT --to-destination <IP ADDR>:7443
-A OUTPUT -d <IP ADDR> -p tcp -m tcp --dport 443 -j DNAT --to-destination <IP ADDR>:7443
COMMIT
  • Restart iptables
  • Remove port 7443 from the following files:
    • /etc/topaz/ambra.xml
    • /etc/topaz/nonJmxApplicationContext.xml

Post Installation

Create Admin User

This needs to be done only once on a freshly installed system

  1. Register as user "Admin" with valid email address
  2. Go through the email confirmation process
  3. Login as the user and fill out the profile
  4. Go to http://[FQHN:port]/admin/findUser.action
  5. Look up your userid using 'Find User by Email' (should be "info:doi/10.1371/account/<GUID>")
  6. Go to the following URL and enter the user id: http://[FQHN:port]/admin/assignAdminRole.action

Ingest Articles

  1. On Ambra server, copy articles into /var/spool/ambra/ingestion-queue
    • Run /usr/local/topaz/bin/prepare_sip on articles if necessary
  2. chown topaz.topaz /var/spool/ambra/ingestion-queue/*.zip
  3. Go to http://[FQHN:port]/admin/adminTop.action
  4. Select an article from the "Ingestable Articles" section
  5. Click on "Ingest Selected Archives"

Publish Articles

  1. Go to http://[FQHN:port]/admin/adminTop.action
  2. Ingested articles will display in the "Publishable Documents" section. You can view an article before it is published by clicking on the article URL. This article is not publicly viewable.
  3. Check "Publish" for an article
  4. Click on "Publish/Delete Articles"

Upgrade Instructions

Stop Applications

Stop all applications in the following order: 

service httpd stop
service ambra stop
service ambra-cas stop
service topaz-fedora stop
service topaz-mulgara stop

Tools upgrade

  • Upgrade tools rpms 
    rpm -Uvh ambra-tools-${version}.noarch.rpm

Mulgara upgrade

  • Upgrade Mulgara rpms 
    rpm -Uvh topaz-mulgara-${version}.noarch.rpm
service topaz-mulgara start

Fedora upgrade

  • There is no need to backup common config files, e.g. /etc/topaz/ambra.xml, as they have been re-packaged
  • There should be no need to "force" the upgrade
  • Upgrade Fedora rpms 
    rpm -Uvh --force topaz-fedora-${version}.noarch.rpm
  • Initialize Fedora - necessary to create xacml policies, etc. 
    service topaz-fedora start
--- wait ---
service topaz-fedora stop
  • Edit /usr/local/topaz/topaz-fedora/data/fedora-xacml-policies/repository-policies/default/deny-apim-if-not-localhost.xml 
    Copy this line:
<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">127.0.0.1</AttributeValue>
And create additional lines below it (one per topaz server):
<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">[IP ADDRESS OF TOPAZ SERVER]</AttributeValue>
  • Fedora server 
    service topaz-fedora start

CAS upgrade

  • Upgrade CAS rpm 
    rpm -Uvh ambra-cas-${version}.noarch.rpm
  • Edit /usr/local/topaz/ambra-cas/webapps/plos-registration/global/global_config.ftl and change FQHN point to Ambra server OR proxy webhead if you're using one. Add port if necessary. No trailing slash. Make sure other fields are valid. 
    <#assign context="/plos-registration">
<#assign plosOneUrl="http://FQHN[:8080]">
<#assign plosOneContext="/ambra-webapp">
  • Update database password in /usr/local/topaz/ambra-cas/webapps/cas/web.xml if necessary
  • Start CAS 
    service ambra-cas start

Ambra upgrade

  • Upgrade Ambra rpm 
    rpm -Uvh ambra-${version}.noarch.rpm
  • restore previous configuration files in /etc/topaz
  • copy settings from ambra.xml.rpmsave to ambra.xml
  • Configure any virtual journals
  • start Ambra 
    service ambra start

Start Apache web server

Start apache on webhead 

service httpd start