ePages Installation Guide for Linux | → 6.15.1 | Created: 6.12.2; Updated: 6.15.1 |
For detailed instructions and information on ePages 6, please visit the ePages helpcenter at http://helpcenter.epages.com .
An ePages 6 system consists of 5 main components:
You can install all of the components on one machine (single server installation), or certain components on specific machines (distributed installation). The installation instructions below describe both scenarios.
ePages is installed from the ePages YUM repository.
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. Get from the web site http://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:
rpm --import b1d28320.txt
Then execute:
rpm -K <filename>.rpm
The command should return:
<filename>.rpm: (sha1) dsa sha1 md5 gpg OK
1. Add ePages to your YUM repository:
curl http://epages.com/RPMS/rpmify/rpmify-epages.sh | sh
If some RPM packages are missing that are required for the ePages installation, a message is shown how to install those packages first. Then re-run the command above.
2. File /etc/sysconfig/epages6 contains variable settings.
All variables are optional and have sensible defaults. Read the variable descriptions in /etc/sysconfig/epages6.
If you want to customize variables, edit /etc/sysconfig/epages6.
If the password of the MySQL user root has changed (i.e. it is neither empty nor epages), change EPAGES_INSTALL_MYSQL_PASS in /etc/sysconfig/epages6 accordingly, e.g.:
export EPAGES_INSTALL_MYSQL_PASS="secret_password"
3. Install and start ePages:
Distributed installation allows you to install certain components of ePages 6 on specific machines:
Executing rpmify-epages.sh installs the installation configuration file /etc/sysconfig/epages6.
All involved servers must use the same configuration file /etc/sysconfig/epages6.
To achive this, following steps must be executed (see sections Custom Installation on Two Machines or Custom Installation on Three Machines below):
A distributed ePages 6 installation requires user and group definitions with the same user and group IDs on all machines.
parameter | defines | default |
---|---|---|
EPAGES_INSTALL_WS_GROUP | web server group name | ep_web |
EPAGES_INSTALL_WS_RUNUSER | user who runs the web server | eprunweb |
EPAGES_INSTALL_AS_RUNUSER | user who runs the application server | eprunapp |
EPAGES_INSTALL_EPAGESJ_USER | user who runs the java server | epagesj |
EPAGES_INSTALL_WS_RUNUID | ID of $EPAGES_INSTALL_WS_RUNUSER | |
EPAGES_INSTALL_WS_UID | ID of the web server file owner | |
EPAGES_INSTALL_WS_GID | ID of the web server group | |
EPAGES_INSTALL_EP_GID | ID of the group epages | |
EPAGES_INSTALL_AS_RUNUID | ID of $EPAGES_INSTALL_AS_RUNUSER | |
EPAGES_INSTALL_AS_UID | ID of the application server file owner ep_appl | |
EPAGES_INSTALL_DB_UID | ID of the database server user ep_db | |
EPAGES_INSTALL_EPAGESJ_UID | ID of $EPAGES_INSTALL_EPAGESJ_USER |
A distributed ePages 6 installation needs to know what hosts shall run what services. Furthermore you may choose what IPs and ports to use (especially if you have more than 1 network card).
Set those parameters in /etc/sysconfig/epages6.
Define server names/IPs and ports in /etc/sysconfig/epages6. All variables ending in _HOST must contain either a host name (long as host1.example.com or short as host1) or an IP address:
parameter | defines |
---|---|
EPAGES_INSTALL_AS_HOST | application server host |
EPAGES_INSTALL_RR_HOST | request router host (typically same as web server) |
EPAGES_INSTALL_WS_HOST | web server host |
EPAGES_INSTALL_EPAGESJ_HOST | java server host |
EPAGES_INSTALL_SOLR_HOST | solr server host |
EPAGES_INSTALL_SOLRSLAVE_HOST | solr slave host |
EPAGES_INSTALL_MONGO_HOST | mongodb server host |
EPAGES_INSTALL_MYSQL_CONNECTION | MySQL server connection string |
For each variable ending in _HOST there is a variable ending in _HOSTIP that defines the IP of the host. Set both variables if hostname and IP are not DNS resolvable or if there is more than 1 network card.
For each variable ending in _HOST there is a variable ending in _PORT defining the server port. These variables are optional and have sensible defaults. Do not change this variables unless you really need to.
If the password of the MySQL user root has changed (i.e. is neither empty nor epages), change EPAGES_INSTALL_MYSQL_PASS in /etc/sysconfig/epages6 accordingly, e.g.:
export EPAGES_INSTALL_MYSQL_PASS="secret_password"
Make sure that all involved machines have the same system time. If you use a network time protocol daemon (as ntpd), make sure that all machines use the same configuration file (as ntp.conf). For more information about the network time protocol daemon, please see the manual pages (as man ntpd).
1. Run rpmify-epages.sh:
curl http://epages.com/RPMS/rpmify/rpmify-epages.sh | sh
2. Edit /etc/sysconfig/epages6 as described in Customizing Installation Parameters (if necessary).
3. Share the file system:
/var/epages/epages-fs.sh -share
4. Install the database server:
/var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i
1. Run rpmify-epages.sh:
curl http://epages.com/RPMS/rpmify/rpmify-epages.sh | sh
2. Mount the previously shared file system (replace HOSTNAME by the hostname of machine 1):
/var/epages/epages-fs.sh -mount HOSTNAME
3. Install the application server, java server, web server and request router:
/srv/epages/eproot/bin/se-webnfs-context.sh --set --no-start /etc/init.d/epages6 start_java
After successful installation first (order is important!) start ePages 6 first on the database server, then on the application/web server:
1. Run rpmify-epages.sh:
curl http://epages.com/RPMS/rpmify/rpmify-epages.sh | sh
2. Edit /etc/sysconfig/epages6 as described in Customizing Installation Parameters (if necessary).
3. Share the installed system:
/var/epages/epages-fs.sh -share
4. Install the application server:
1. Run rpmify-epages.sh:
curl http://epages.com/RPMS/rpmify/rpmify-epages.sh | sh
2. Mount the previously shared file system (replace HOSTNAME by the hostname of machine 1):
/var/epages/epages-fs.sh -mount HOSTNAME
3. Install the database server:
/var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i
1. Run rpmify-epages.sh:
curl http://epages.com/RPMS/rpmify/rpmify-epages.sh | sh
2. Mount the previously shared file system (replace HOSTNAME by the hostname of machine 1):
/var/epages/epages-fs.sh -mount HOSTNAME
3. Install web server and request router:
/srv/epages/eproot/bin/se-webnfs-context.sh --set --no-start
5. Ignore ePages schedulers on web server (or change $EPAGES_CONFIG/Scheduler.conf manually):
/var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i
After successful installation first (order is important!) start ePages 6 first on the web server, second on the database server, third on the application server:
If ePages is installed on 2 machines as described in Custom Installation on Two Machines, you may simply add a further application server to achive load balancing and scalability.
This sections describes how to add a further application server to your system.
The ePages installation will still work if one of the application servers is down. If the database server is down, ePages won't work anymore. To achive this you must replicate database server, file server and load balancer by your own.
Following description works only for ePages installations with initial version 6.15.1 or higher. If you want to use load balancing as described here on older installations:
1. update ePages to (at least) 6.15.1, 2. backup the original Apache configuration in /etc/httpd (resp. /etc/apache2), 3. execute on any host with epages web server:
/srv/epages/eproot/bin/use-local-httpd.sh -r
First install ePages on 2 machines as described in Custom Installation on Two Machines.
Configure the application server (replace _IP_ by the IP of machine 1):
/var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DRPAF"' -i /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP -v _IP_ -i
Install ePages on a additional machine in the same way as described in Machine 2: Application Server, Java Server and Web Server.
On the additional application server, configure epages (replace _IP_ by the IP of machine 1):
/var/epages/ini-config.sh -f /srv/epages/eproot/j/conf/epagesj.conf -k host -v $(hostname --fqdn) -i /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGESJ_HOST -v $(hostname --fqdn) -i /var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DRPAF"' -i /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP -v _IP_ -i /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i rm -f /srv/epages/eproot/Shared/Config/appsrv.ini
If SELinux is enabled on your Red Hat host, files must be remounted so that the web server can access them:
/srv/epages/eproot/bin/se-webnfs-context.sh --set --no-start /etc/init.d/epages6 start_java
Go on with installing/configuring the load balancer.
Install (unless already done) the load balancer on the database server (machine 1):
On the load balancer, configure the Apache web server (replace "machine2.example.com machine3.example.com" by your application server list):
/var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DLB"' -i /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "(machine2.example.com machine3.example.com)" -i
and (unless already done) change the domain name in the databases:
. /etc/default/epages6 $PERL $EPAGES_CARTRIDGES/DE_EPAGES/ShopConfiguration/Scripts/ChangeDomainName.pl -address $(hostname --fqdn)
After that change, new ePages URLs are http://machine1.example.com/... resp. https://machine1.example.com/... (replace machine1.example.com by the domain name of your load balancer).
After successful installation first restart ePages on the load balancer (machine 1):
/etc/init.d/epages6 start
Then on the application server(s) already existing before enhacement:
/etc/init.d/epages6 start
Then on the new application server:
Check if the load balancer works by accessing the web page http://machine1.example.com/balancer-manager (replace machine1.example.com by the name of the load balancer).
Because the page is 'Allow from' restricted, the IP of your desktop (where you run the web browser) must be mentioned in the environment variable EPAGES_ALLOW_FROM= in /etc/default/epages6.
Allow access for your desktop (e.g. 1.2.3.4) to the restricted page by executing following commands on the load balancer as well on all balancer members:
/var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_ALLOW_FROM -v '"1.2.3.4"' -i /etc/init.d/epages6 start_httpd
Another restricted page shows you request statistics handled by the request routers: http://machine1.example.com/Monitor/spy.pl
The number of request routers shown there should be equal to the number of epages hosts (if you installed ePages as described before).
If at least one of the application servers is still running, ePages will stay working.
If the primary applications server goes down, one other server must overtake the scheduler jobs, run on this server:
/var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v "" -i /etc/init.d/epages6 start_cron
If a application server goes live again, restart the load balancer:
/etc/init.d/epages6 start_httpd
If the primary application server goes live again:
1. shut down the scheduler jobs on the failover server:
/etc/init.d/epages6 stop_cron /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i
2. restart the request router on any application server:
/etc/init.d/epages6 start_rr
It is also possible to install load balancer and balancer member on the same machine. This might be not very useful in a productive environment, but you can test load balancing on a single server. This section shows how to use load balancing on a single server installation, afterwards extended by a further balancer member on a different host.
If the load balancer runs on one host, and the balancer members run on other hosts (each on a different, say machine2 and machine3), then following environment variables must be set on the load balancer:
/var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DLB"' -i /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "(machine2 machine3)" -i
and following environment variables must be set on each balancer member (_IP_ is IP of load balancer):
/var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DRPAF"' -i /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP -v _IP_ -i
This we did in section Custom Installation with Load Balancing.
If ePages was installed as Single Server Installation, add load balancing by setting environment variables as follows (assuming `hostname` is resolvable by dig):
/var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DLB"' -i /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP \ -v $(dig +short $(hostname) +search +noall +answer | head -1) -i /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "(8008)" -i
This is rather proxying than load balancing because (until now) we only have one balancer member: the web server on port 8008 (port may vary).
The SSL port of the balancer member defaults to 8443, you may change this (to e.g. 8444) by executing:
/var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS_SSL -v "(8444)" -i
Start the load balancer and the balancer member:
/etc/init.d/epages6 start_httpd
Check if everything works fine, see section Load Balancer Monitor.
On the load balancer, share the file system:
/var/epages/epages-fs.sh -share
Add a further balancer member as described in Install Additional Application Server.
On the new balancer member, start ePages:
/etc/init.d/epages6 start
On the load balancer, add a new balancer member (replace machine2.example.com by the name of the new host):
x=$(/var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -g) x="${x%)*} machine2.example.com)" /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "$x" -i
If you changed BALANCER_MEMBERS_SSL before, run same commands with BALANCER_MEMBERS_SSL.
On the load balancer, start epages:
/etc/init.d/epages6 start_httpd
Check if everything works fine, see section Load Balancer Monitor.
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:
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 | stop | includes web, database, 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:
/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'.
After starting ePages you should be able to view following web pages (where www.example.com is the name of your web server incl. domain):
Execute on any involved computer (use instead of epages the groups you did install):
/var/epages/delete-epages.sh