Installing Ambra and services on single linux machine using RPMs

This page outlines installing the publishing system on a single linux machine using RPM packages.

See also:

• SingleBoxInstallScript
• MultiBoxInstall

The latest packages can be downloaded from:

• Ambra
• Ambra CAS
• Ambra Tools/Scripts
• Topaz Mulgara Triple Store
• Topaz Fedora Blob Store

Configuration Summary

Ports required:

init	start-pri	stop-pri	port	ssl	shutdown-port
ecqs	91	15	----	7443	7005
mulgara	92	14	8111 (tql/RMI)	----	6789
fedora	93	13	9090 (http)	9443	9005
ambra	96	10	8080 (http) 8009 (ajp) 8112,8113 (echache/RMI)	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:

• FQHN

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: (only necessary for PostgreSQL <= 7)

  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
  

• Configure any virtual journals

• 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:

• configure the jpackage yum repository (http://www.jpackage.org/yum.php)

• 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