The official documentation is at: http://docs.alfresco.com
This page documents a simple way to get tomcat session replication using Memcached as a backing store, instead of relying on tomcat's own replication (e.g. DeltaManager etc).
Benefit
In a clustered environment, if a node becomes unavailable, users that were connected to that node will not lose their session, and will not have to log in again.
This configuration is completely independent of alfresco clustering itself. It is only related to replicating the application server sessions.
Setup steps
Get the software
- download memcached-session-manager-x.y.z.jar, memcached-session-manager-tc6-x.y.z.jar (or memcached-session-manager-tc7-x.y.z.jar if using Tomcat 7) from https://code.google.com/p/memcached-session-manager/downloads/list.
- download the couchbase java client from http://www.couchbase.com/communities/java/getting-started. It includes spymemcached-x.y.z.jar which is also necessary later.
- copy all 4 jars in tomcat/lib (on all tomcat nodes). At the time of writing, the latest avaible versions for these jars are 1.2.0 for the couchbase client, 2.10.0 for spymemcached, and 1.6.5 for both memcached-session-manager jars
tomcat configuration
Session Manager configuration
- edit tomcat/conf/context.xml, and add the following lines inside the <Context> tag (on all nodes):
<Manager className='de.javakaffee.web.msm.MemcachedBackupSessionManager'
memcachedNodes='n1:localhost:11211'
requestUriIgnorePattern='.*\.(ico|png|gif|jpg|css|js)$' />
All the parameters are documented here , if required.
11211 is the default port memcached starts on. More complex configurations are not required for this simple working example.
logging configuration
This could be considered optional, but keeps the logging to a minimum to avoid flooding the logs.
- edit tomcat/conf/logging.properties (on all nodes) :
# A handler's log level threshold can be set using SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL
net.spy.memcached.level = WARNING
de.javakaffee.web.msm.level = WARNING
- add the following in your JVM options, usually your JAVA_OPTS environment variable :
-Dnet.spy.log.LoggerImpl=net.spy.memcached.compat.log.SunLogger'
(see Logging config for more details).
The tomcat instances are now configured.
installing memcached
memcached is packaged in all major Linux distributions. you can get it installed with e.g.
yum install memcached
Adjust for other OSes / distributions if required. The default memcached settings don't need to be changed, at least for this example.
load balancer configuration
This is beyond the scope of this wiki page, but here you would configure a load balancer in front of the tomcat instances. Frequently, it is either Apache httpd with either mod_jk or mod_proxy_balancer.
Whichever solution is chosen, do not forget to :
- enable sticky sessions (aka sticky routing).
- reflect the name of the chosen workers/members in each of the tomcat nodes in conf/server.xml, by adding a jvmRoute attribute in the <Engine> tag. (e.g. jvmRoute='node1' with a worker named node1 for mod_jk, or a balanceMember with route=node1 for mod_proxy_balancer).
Starting the services
service memcached start
- start your frontend load balancer (httpd in the example mentionned above)
- the tomcat nodes can now be started in turn, using the usual means (e.g. startup scripts, services, ... ). Session information will be replicated through memcached, and users will not have to log in again if the node they're connected to goes down.
Testing
This configuration can be tested by :
- assuming the front-end load balancer is listening on port 80, logging in to e.g http://localhost/share
- navigate to a site for example
- inspecting the node you're connected to (using either jkstatus, inspecting the JSESSIONID cookie in the browser, ...)
- shut this node down
- refresh the page or click another link on the page
- notice that you're still connected, have not been asked to log in, and that the jsession ID cookie has been rewritten with the new JVM route
Note : failover stats are also exposed as JMX, see https://code.google.com/p/memcached-session-manager/wiki/JMXStatistics.
Note : more detailed logging can be obtained by adjusting the logging configuration mentionned above.
Note : original instructions used are available here : http://www.bradchen.com/blog/2012/12/tomcat-auto-failover-using-apache-memcached.
Optional config
Making memcached highly available
Note : A single memcached instance is used here for the example. Memcached itself could be made HA.
- memcached replication with repcache. Makes memcached HA but to add memcached nodes you would need to add them in context.xml and restart tomcat
- to improve this, a load balancer could be put in front of the memcached nodes, such as balance. This would decouple the list of nodes from the tomcat configuration.
- the load balancer itself could be made HA with a moving virtual IP, with things like linux director (aka ldirectord) & heartbeat/pacemaker. See here and here as a starting point.
- additional note : looks like couchbase could be used a memcache backend too, instead of repcache, see http://www.couchbase.com/memcached. It comes with its own clustering / replication mechanisms.
- additional note : as an alternative, Infinispan could apparently be used also as a memcached backend too, see https://docs.jboss.org/author/display/ISPN/Using+Infinispan+Memcached+Server.
- MySQL 5.6 from Oracle also has a new memcache storage engine, which could be used in theory : http://dev.mysql.com/doc/refman/5.6/en/innodb-memcached-setup.html. Not currently in MariaDB apparently.
Performance
