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=http://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:
-
Create configuration files in /srv/epages/eproot/Shared/Config
-
Install ePages packages (.rpm or .deb)
-
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=http://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=http://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=http://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=http://epages-software.de/repo/usr/$UUID
/var/epages/install-epages.sh --singlehost --version $VERSION --repo $REPOURL
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=http://epages-software.de/repo/usr/$UUID
/var/epages/install-epages.sh --singlehost --unpack --version 7.37.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:
-
Install epages-release which provides /srv/epages/etc/sysconfig and /var/epages/install-epages.sh
-
Use files in /srv/epages/etc/sysconfig as a sample for your configuration files
-
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=http://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 /Doc/doc/epages/install-epages.conf.sample.html[/srv/epages/etc/sysconfig/install-epages.conf.sample]):
- patchhost=/Doc/doc/epages/patchhost.conf.html[patchhost.conf]
-
host runs the ePages initial installation and patches
patchhost.conf contains environment variables for installation and patch
- appsrv=/Doc/doc/epages/appsrv/localhost.conf.html[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=/Doc/doc/epages/ascsrv/localhost.conf.html[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=/Doc/doc/epages/reqsrv/localhost.conf.html[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=/Doc/doc/epages/mysqld/simple.conf.html[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 /Doc/doc/epages/mysqld/complex.conf.html[mysqld/complex.conf] for how to add (cartridges/languages to) business units.
- webconf=1
-
host runs a web server (Apache)
- j=/Doc/doc/epages/j/localhost.conf.html[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=http://epages-software.de/repo/usr/$UUID
/var/epages/install-epages.sh --version 7.37.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:
-
First run install-epages.sh on the file server.
-
Run install-epages.sh on ePages Java server only after creating epagesj database (executed by install-epages.sh on right MySQL server).
-
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).
-
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=http://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=http://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=http://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=http://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:
-
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).
-
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:
-
Update epages-release.
-
Update new RPMs with yum (epages-patch as last package!).
-
use your own UUID
UUID=1234abcd-1234-1234-1234-0123456789abcd export EPAGES_REPOURL=http://epages-software.de/repo/usr/$UUID rpm -hUv $EPAGES_REPOURL/yum/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:
-
Update epages-release.
-
Update new DEBs with apt-get (epages-patch as last package!).
-
use your own UUID
UUID=1234abcd-1234-1234-1234-0123456789abcd export EPAGES_REPOURL=http://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
-
Run on each server but the file server:
/var/tmp/epages-fs.sh -unmount yum remove ...
-
means all packages you installed with yum install … before.
-
-
Run on the file server:
/var/tmp/epages-fs.sh -unshare yum remove ...
-
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=http://epages-software.de/repo/usr/$UUID
# rpm -K $EPAGES_REPOURL/yum/epages-release.noarch.rpm
http://epages-software.de/repo/usr/1234abcd-1234-1234-1234-0123456789abcd/yum/epages-release.noarch.rpm: (sha1) dsa sha1 md5 gpg OK
YUM Troubleshooting
Metadata File Does Not Match Checksum
Problem:
http://epages-software.de/repo/usr/1234abcd-1234-1234-1234-0123456789abcd/yum/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/yum/__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