ePages Installation Preliminaries

If you just want to install ePages on a dedicated host then continue with section Basic ePages Installation.

Components of an ePages Installation

ePages can be installed either on Red Hat/CentOS (with RPM packages) or Debian (with DEB packages).

An ePages system consists of 5 main components:

[AS]

Application server (Perl 5.12.3 and ePages Perl modules, package epages-appsrv)

[RR]

Request router (package epages-reqsrv) and ASCache server (package epages-ascsrv)

[DB]

Database server (MySQL configuration, package epages-mysqld)

[WS]

Web server (Apache configuration, package epages-webconf)

[JS]

Java server (ePages Java code, package epages-j)

The packages can be installed on one machine (single server installation), or distributed over various machines (distributed installation). The installation instructions below describe both scenarios.

System Requirements

  • Operating system Red Hat Enterprise Linux / CentOS or Debian (see Supported Operating Systems For ePages Installations)

  • Computer with AMD64/Intel64(EM64T) processor (only supported by Red Hat)

  • At least 8 GB RAM (more is recommended)

  • At least 100 GB disk space (base installation)

  • TCP/IP and DNS must be installed; the command host host_name (where host_name is the name of your host) must return the IP address of the host

  • SMTP server connection to send system generated emails

  • The host name must not point to the local interface (127.0.0.1 or 127.0.0.2, see /etc/hosts)

  • Web browser Mozilla Firefox or Google Chrome

  • If you want to run the shop via SSL, a SSL certificate must be installed

Time Server

System time on all involved hosts must be the same and correct. If a network time protocol daemon (as ntpd) is used, all machines must use the same configuration file (as ntp.conf). For more information about the network time protocol daemon, see the manual pages (as man ntpd).

UUID

Starting with ePages 7.5.0 you’ll need a personal UUID to install ePages.

Contact ePages support to get your UUID.

Hereinafter we use as example UUID is 1234abcd-1234-1234-1234-0123456789abcd, replace this by your personal UUID.

Basic ePages Installation

Single Server Standard Installation

Install the latest version of ePages on a single host by executing (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
curl -L $EPAGES_REPOURL/install-epages.sh | bash

Installing ePages Packages Without Starting ePages

install-epages.sh installs the ePages packages in the following way:

  1. Create configuration files in /srv/epages/eproot/Shared/Config

  2. Install ePages packages (.rpm or .deb)

  3. If a package has a postinstall script, run it (e.g. for epages-mysqld create the ePages databases)

If you want to execute just step 2 then run (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
export EPAGES_INSTALLATION='unpack'
curl -L $EPAGES_REPOURL/install-epages.sh | bash

If you want to execute just steps 1 and 2 then run (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
export EPAGES_INSTALLATION='nostart'
curl -L $EPAGES_REPOURL/install-epages.sh | bash

Basic Options for Repository, Version and Package Handling

If you want more customization run /var/epages/install-epages.sh with options on the command line. This also has the advantage that installation log files are created in /tmp/epages.

For that you must first install the package epages-release which provides /var/epages/install-epages.sh (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
export EPAGES_INSTALLATION='-epages'
curl -L $EPAGES_REPOURL/install-epages.sh | bash

Then you may run /var/epages/install-epages.sh with the options described below.

Set Version

If you want to install a different ePages version run (replace 6.17.34 with your version, use your own UUID):

VERSION=6.17.34
UUID=1234abcd-1234-1234-1234-0123456789abcd
REPOURL=ftp://epages-software.de/repo/usr/$UUID
/var/epages/install-epages.sh --singlehost --version 7.15.0 --repo $REPOURL --version $VERSION

Just Unpack Packages

Use options --unpack or --nostart in a similiar way as described above (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
REPOURL=ftp://epages-software.de/repo/usr/$UUID
/var/epages/install-epages.sh --singlehost --unpack --version 7.15.0 --repo $REPOURL

Single Server Installation with Configuration Files

With command line arguments you only can customize ePages version and repository. Any other customization must be done via configuration files, for example:

  • changing the standard business unit set (Site and Store) to something other

  • adding ePages cartridges to business units

  • defining languages for business units

  • setting parameters for ePages cartridges

  • setting the number of application processes

  • setting passwords for MySQL users

Sample configuration files can be found in /srv/epages/etc/sysconfig from package epages-release. Running install-epages.sh with configuration files shall be done in three steps:

  1. Install epages-release which provides /srv/epages/etc/sysconfig and /var/epages/install-epages.sh

  2. Use files in /srv/epages/etc/sysconfig as a sample for your configuration files

  3. Run /var/epages/install-epages.sh --configfile install-epages.conf

Install Package epages-release

First install epages-release (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
export EPAGES_INSTALLATION='-epages'
curl -L $EPAGES_REPOURL/install-epages.sh | bash

Customize Configuration Files

Use install-epages.conf.sample as a sample for your configuration file:

cd /srv/epages/etc/sysconfig
/bin/cp -p install-epages.conf.sample install-epages.conf

Add user information for already existing ePages users (created in previous step above):

cd /srv/epages/etc/sysconfig
id=($(awk -F: '/^ep_appl:/{print $3 " " $4}' /etc/passwd))
/var/epages/ini-config.sh -f install-epages.conf -k ep_appl -v "${id[0]}" -i
/var/epages/ini-config.sh -f install-epages.conf -k epages -v "${id[1]}" -i

Configuration files in /srv/epages/etc/sysconfig already have reasonable values. However, you may edit those configuration files.

Configuration Files Contents

Option --configfile of /var/epages/install-epages.sh defines the base configurations file. Some keys in the base configurations file may point to other configuration files for specific ePages services.

The base configuration file has following sections:

general information

common settings for all servers

unix groups

group name - group ID mapping for ePages groups

unix users

user name - user ID mapping for ePages users

All other sections are (fully qualified or short) hostnames. If a host runs /var/epages/install-epages.sh then it notes only its own section. If no own section found but section localhost exists then it uses this localhost section.

Each hostname sections defines (beside some general settings) what ePages services shall be run and what special configuration files they use.

If a ePages services key is missing, empty or set to 0 then then this service is not used. Otherwise it is. Then, the value of the service key may be a service configuration file path relative to the base configuration file.

For example, if /srv/epages/etc/sysconfig/install-epages.conf contains patchhost=patchhost.conf then patchhost.conf is stored in /srv/epages/etc/sysconfig/patchhost.conf.

Following service keys can be used (see /srv/epages/etc/sysconfig/install-epages.conf.sample):

patchhost=patchhost.conf

host runs the ePages initial installation and patches

patchhost.conf contains environment variables for installation and patch

appsrv=appsrv/localhost.conf

host runs an ePages application server

appsrv/localhost.conf contains settings for WebInterface.conf and ServerConfig.xml. Here you can change the number of the application servers (by extending the ports= range) or the maxmemory= (in MB) each appserver can consume.

ascsrv=ascsrv/localhost.conf

host runs an ePages ASPoolDB cache server

ascsrv/localhost.conf contains settings for ServerConfig.xml. You should not change this for single server installations.

reqsrv=reqsrv/localhost.conf
host runs an ePages request router

reqsrv/localhost.conf contains settings for ServerConfig.xml. You should not change this for single server installations.

mysqld=mysqld/simple.conf
host runs a MySQL server

mysqld/simple.conf defines what business units the server shall provide and some configuration for the business units. See as well mysqld/complex.conf for how to add (cartridges/languages to) business units.

webconf=1

host runs a web server (Apache)

j=j/localhost.conf

host runs a

ePages Java server

j/localhost.conf may contain the secret.key for epagesj

Install ePages with Configuration Files

After customizing the configuration start install-epages.sh (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
REPOURL=ftp://epages-software.de/repo/usr/$UUID
/var/epages/install-epages.sh --version 7.15.0 --repo $REPOURL --configfile install-epages.conf

Log Files for ePages Installation

Find log files of the ePages installation in:

  • /tmp/epages

  • /srv/epages/eproot/Shared/Log

Distributed Installation with Configuration Files

ePages services can be distributed over different hosts. The same service (as e.g. the application server) may reside on various hosts. Business units may be distributed over various hosts.

The base configuration file install-epages.conf defines hostname sections. Each section contains as keys the services which shall be run on that host.

Following service keys can be selected:

fileserver

stores the Shared/ file system (define exactly 1 host as file server)

appsrv

ePages application server

patchhost

application server that runs the ePages initial installation and patches (define exactly 1 host as patch host)

ascsrv

ePages ASPoolDB cache server

reqsrv

ePages request router

mysqld

MySQL server

webconf

Apache web server

j

ePages Java server

ePages must be installed on the distributed hosts in a specific order:

  1. First run install-epages.sh on the file server.

  2. Run install-epages.sh on ePages Java server only after creating epagesj database (executed by install-epages.sh on right MySQL server).

  3. Run install-epages.sh on ePages ASPoolDB cache server / Request Router only after creating ASPoolDB database (executed by install-epages.sh on right MySQL server).

  4. Finally run install-epages.sh on the patch host.

If these dependencies are conflicting then single services may be installed by using option --distributed. For example, if the base configuration file defines the services mysqld, ascsrv and reqsrv to be installed on one host then you may install first the database:

/var/epages/install-epages.sh --distributed mysqld --configfile install-epages.conf

and later the ASPoolDB cache server and Request Router:

/var/epages/install-epages.sh --distributed 'ascsrv reqsrv' --configfile install-epages.conf

Example Part 1: Customize Configuration Files on File Server

In following example we assume ePages distributed over three hosts:

  • Patch host named asjs.example.com provides application server, Java server and file server

  • Host named wsrr.example.com provides request router, ASPoolDB cache server and Apache web server

  • Host named db.example.com provides MySQL server

First install package epages-release on file server (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
export EPAGES_INSTALLATION='-epages'
curl -L $EPAGES_REPOURL/install-epages.sh | bash

Then create install-epages.conf as required before:

cd /srv/epages/etc/sysconfig
cat >>install-epages.conf <<HERE
[asjs.example.com]
fileserver=server
patchhost=1
appsrv=1
j=1
[wsrr.example.com]
fileserver=client
ascsrv=1
reqsrv=1
webconf=1
[db.example.com]
fileserver=client
mysqld=1
HERE

Example Part 2: Install ePages on distributed servers

After starting the file server and configuring the installation, run install-epages.sh on the MySQL server (note that you must define the used file server in EPAGES_INSTALLATION, use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
export EPAGES_INSTALLATION='fileserver=asjs.example.com'
curl -L $EPAGES_REPOURL/install-epages.sh | bash
CFG=/srv/epages/etc/sysconfig/install-epages.conf
/var/epages/install-epages.sh --version $VERSION --repo $EPAGES_REPOURL --configfile $CFG

Then run install-epages.sh on wsrr.example.com (note that you must define the used file server in EPAGES_INSTALLATION, use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
export EPAGES_INSTALLATION='fileserver=asjs.example.com'
curl -L $EPAGES_REPOURL/install-epages.sh | bash
CFG=/srv/epages/etc/sysconfig/install-epages.conf
/var/epages/install-epages.sh --version $VERSION --repo $EPAGES_REPOURL --configfile $CFG

Finally go back to the file server (which is also patch host) and run (use your own UUID):

UUID=1234abcd-1234-1234-1234-0123456789abcd
export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
CFG=/srv/epages/etc/sysconfig/install-epages.conf
/var/epages/install-epages.sh --version $VERSION --repo $EPAGES_REPOURL --configfile $CFG

Starting and Stopping Services

Services may be started automatically (initlevel or rc scripts) or manually by the UNIX command:

/etc/init.d/epages6 <start parameter>

Services may be stopped automatically (initlevel or rc scripts) or manually by the UNIX command:

/etc/init.d/epages6 <stop parameter>

<parameter> defines the components of the application involved:

{| border=1 ! start parameter ! stop parameter ! controls |- | start_httpd | stop_httpd | web server (only if installed and configured with epages) |- | start_service | stop_service | application server |- | start_rr | stop_rr | request router |- | start_db | stop_db | database server |- | start_java | stop_java | includes mongod, epagesj, epages-solr, epages-solr-slave |- | start | stop | includes web, database, java and application server |- | show |   | show all running ePages processes |}

A manual start of an active service causes that service to stop and restart.

Starting the SSL web server works only if:

  1. The SSL certificate file for the web server is stored in $HTTPD_ROOT/conf/ssl.crt/server.crt (where $HTTPD_ROOT is for example /etc/httpd).

  2. The SSL certificate key file for the web server is stored in $HTTPD_ROOT/conf/ssl.key/server.key (where $HTTPD_ROOT is for example /etc/httpd).

The epagesj server is started as follows:

/etc/init.d/epagesj start

The solr server is started as follows:

/etc/init.d/epages-solr start

The solr slave server is started as follows:

/etc/init.d/epages-solr-slave start

Stop all servers with stop, show status of those servers with status.

Patching ePages

ePages may be patched by yum/apt-get (as described below) or on command line. For detailed instructions and information on patching ePages, see ePages Patch Installation.

Red Hat: Patch ePages to the Latest Version

Patching ePages consists of three steps:

  1. Update epages-release.

  2. Update new RPMs with yum (epages-patch as last package!).

  3. use your own UUID

    UUID=1234abcd-1234-1234-1234-0123456789abcd
    export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
    rpm -hUv $EPAGES_REPOURL/7.15.0/epages-release.noarch.rpm
    yum -y update 'epages-[a-oq-z]*' --disablerepo epages-setup --enablerepo epages-update
    yum -y update epages-patch --disablerepo epages-setup --enablerepo epages-update

Debian: Patch ePages to the Latest Version

Patching ePages consists of three steps:

  1. Update epages-release.

  2. Update new DEBs with apt-get (epages-patch as last package!).

  3. use your own UUID

    UUID=1234abcd-1234-1234-1234-0123456789abcd
    export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
    curl -LO $EPAGES_REPOURL/apt/epages-release_all.deb
    dpkg -i epages-release_all.deb
    apt-get -y update
    apt-get -y --only-upgrade install 'epages-[^pt]'
    apt-get -y install epages-patch

Log Files for Patches

If a patch is installed with YUM following log files are written (version 6_17_6 may vary):

/tmp/epages-patch_6_17_6-prerequisites.log

contains the output of the patch pre-installation commands

/tmp/epages-patch_6_17_6-install.log

contains the output of the patch installation commands

/srv/epages/eproot/Shared/Patches/var_patch_VERSION/

contains the output of the patch API

Installing ePages Patch Files Without Starting the Patch

If you want to install the patch files into $EPAGES_SHARED/Patches/patch_X_Y_Z/ but don’t want to start the patch executing ./patch.sh install, run:

yum -y update 'epages-[a-oq-z]*' --disablerepo epages-setup --enablerepo epages-update
EPAGES_DO_PATCH=0 yum -y update epages-patch --disablerepo epages-setup --enablerepo epages-update

Then after installing the patch files, run following commands to install the patch itself:

cd $EPAGES_SHARED/Patches/patch_*
./patch.sh install

Customizing the ePages Patch Installation

  • If you want to use your own prerequisits.ini file (instead of the one provided by the patch), run (EPAGES_PREREQ_INI= may vary):

    EPAGES_PREREQ_INI=/tmp/prerequisits.ini yum update epages-patch --disablerepo epages-setup --enablerepo epages-update
  • If you want to use your own Conf/ directory (instead of the one provided by the patch), run (EPAGES_PATCH_CONF= may vary):

    EPAGES_PATCH_CONF=/path/to/Conf yum update epages-patch --disablerepo epages-setup --enablerepo epages-update

Read the prerequisits.ini file resp. the Conf/ directory provided by the patch to find customizable parameters.

Patching Distributed Installations

Section Patch a Distributed ePages Installation in document ePages Patch Installation explains how to patch a distributed installation.

Removing ePages

You may remove a single server ePages installation by executing:

on Red Hat:

yum remove @epages

on Debian:

apt-get remove epages

Both commands do not remove ePages completely, changed files remain on the server. To remove ePages on a single server completely, run:

/var/epages/delete-epages.sh

This removes all ePages RPMs/DEBs, files, users, and databases.

Removing Distributed Installations on Red Hat

  1. Run on each server but the file server:

    /var/tmp/epages-fs.sh -unmount
    yum remove ...
    1. means all packages you installed with yum install … before.

  2. Run on the file server:

    /var/tmp/epages-fs.sh -unshare
    yum remove ...
    1. means all packages you installed with yum install … before.

This does not remove ePages completely, changed files remain on the server. To remove ePages completely, run (first on each server but the file server, then on the file server):

/var/epages/delete-epages.sh

ePages Repositories and Packages

ePages RPM packages (see above) are provided by different ePages YUM repositories.

ePages DEB packages (see above) are provided by different ePages APT repositories.

  • new installation (epages-setup.repo) or update (epages-update.repo)

  • architecture/kernel packages (epages-arch.repo and epages-base.repo)

ePages YUM repository configuration files are stored in /etc/yum.repos.d/epages-*.repo.

ePages APT repository configuration file is stored in /etc/apt/sources.list.d/epages.list.

Installing the package epages-release adds following files to the system:

/var/epages/

directory with shell scripts required for installing ePages

/etc/sysconfig/epages6
/etc/pki/rpm-gpg/RPM-GPG-KEY-epages

public key for signatures of ePages RPM files

/etc/debsig/policies/9798CC69B1D28320/epages.pol

public key for signatures of ePages DEB files

/etc/yum.repos.d/epages

RPM repository configuration files

/etc/apt/sources.list.d/epages.list

DEB repository configuration file

Verify RPM Packages on Red Hat

All ePages RPM packages are signed by a GNU Privacy Guard (GPG) key. If you want to verify that a RPM package was really made by ePages, you need the public key. Unless already installed as part of epages-release, get it from the web site http://www.epages.com/security/b1d28320.txt .

To show which key was used to sign an ePages RPM package, run the command:

rpm --checksig -v <filename>.rpm

To verify the signature of an ePages RPM package, first import the public key (unless installed already package epages-release):

rpm --import b1d28320.txt

Then execute:

rpm -K <filename>.rpm

The command should return:

<filename>.rpm: (sha1) dsa sha1 md5 gpg OK

Example (use your own UUID):

# UUID=1234abcd-1234-1234-1234-0123456789abcd
# export EPAGES_REPOURL=ftp://epages-software.de/repo/usr/$UUID
# rpm -K $EPAGES_REPOURL/7.15.0/epages-release.noarch.rpm
ftp://epages-software.de/repo/usr/1234abcd-1234-1234-1234-0123456789abcd/7.15.0/epages-release.noarch.rpm: (sha1) dsa sha1 md5 gpg OK

YUM Troubleshooting

Metadata File Does Not Match Checksum

Problem:

ftp://epages-software.de/repo/usr/1234abcd-1234-1234-1234-0123456789abcd/7.15.0/i386/repodata/filelists.xml.gz: [Errno -1] Metadata file does not match checksum

Solution:

yum clean all

Protected Multilib Versions

Problem:

yum install krb5-libs.i686 openssl.i686 openssl098e.i686
...
Error: Protected multilib versions: openssl-1.0.0-20.el6.i686 != openssl-1.0.0-10.el6_1.4.x86_64
Error: Protected multilib versions: krb5-libs-1.9-22.el6_2.1.i686 != krb5-libs-1.9-9.el6_1.1.x86_64
 You could try using --skip-broken to work around the problem
 You could try running: rpm -Va --nofiles --nodigest

Solution:

yum install --setopt=protected_multilib=false krb5-libs.i686 openssl.i686 openssl098e.i686

File Conflicts

Problem:

yum install openssl.i686
...
Transaction Check Error:
  file /usr/share/doc/openssl-1.0.0/README.FIPS from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
  file /usr/share/man/man1/ca.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
  file /usr/share/man/man1/openssl.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
  file /usr/share/man/man1/req.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
  file /usr/share/man/man1/x509.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64

Solution 1 (preferred):

yum -y install yum-utils
mkdir -p download && cd download
yumdownloader --resolve openssl.i686
mv openssl-*.i686.rpm ..
rpm -hUv *.rpm
cd ..
rpm -hiv --nodocs openssl-*.i686.rpm

Solution 2:

rpm -qa --qf '%{name}-%{version}-%{release}.%{arch}\n' 2>&1 | grep openssl
# openssl-1.0.0-10.el6_1.4.x86_64
rpm -e --justdb --nodeps openssl-1.0.0-10.el6_1.4.x86_64
yum install krb5-libs.i686 openssl.i686 openssl098e.i686

TypeError: Unsupported Operand Type

Problem:

yum groupinstall epages
...
Total download size: 220 M
Is this ok [y/N]: y
Downloading Packages:
Traceback (most recent call last):
File "/usr/bin/yum", line 29, in ?
yummain.user_main(sys.argv[1:], exit_code=True)
File "/usr/share/yum-cli/yummain.py", line 229, in user_main
errcode = main(args)
File "/usr/share/yum-cli/yummain.py", line 181, in main
return_code = base.doTransaction()
File "/usr/share/yum-cli/cli.py", line 386, in doTransaction
  problems = self.downloadPkgs(downloadpkgs, callback_total=self.download_callback_total_cb)
File "/usr/lib/python2.4/site-packages/7.15.0/__init__.py", line 1108, in downloadPkgs
remote_size += po.size
TypeError: unsupported operand type(s) for +=: 'int' and 'str'

Solution:

yum -y install yum-utils
mkdir -p download && cd download
yumdownloader --resolve yum-metadata-parser
rpm -hiv --force yum-metadata-parser-*.el5.i386