Installation & maintenance

From Complete Cyclos documentation wiki
Jump to: navigation, search


  • The current stable release is cyclos_3.6.1
  • The newest development release is cyclos_3.7_rc1

Cyclos uses the following release names and numbering:

cyclos_[Major release number].[Minor release number][Development status number]
  • [Major release number]: major changes (e.g. mayor release 1 to 2 was a refactoring of the entire account system).
  • [Minor release number]: releases that contain various new functions groups and modules.
  • [Development status number]: the status can be:
    • for development releases: "_dev" (development), "_a" (alpha), "_b" (beta), "_rc" (release candidate).
    • for stable releases: .1, .2, .3, etc.

Stand alone (quick) installation

This package of Cyclos can be used to test or evaluate the Cyclos software. It does not need anything pre-installed or configured. Just unzip the file and run the start-cyclos script. This version uses Jetty (instead of tomcat) and an embedded database (HSQL). The basic install can also be used as a production version but in this case we recommend to switch from the HSQL to MySQL database. This stand alone version offers the same functionality as the standard installation.

Installation requirements

  • A computer with operating system Windows 2K, XP, Vista, 7 or any Linux distribution.
  • Java installed (java 6)
  • Stand alone package cyclos_version

Cyclos stand alone installation steps

  • Download the latest stand alone package of Cyclos from sourceforge.
  • If you do not have Java installed, please install it:
  • Unzip the standalone file in a directory (for windows e.g. in "C:\"). The directory cyclos_version will be created (for windows e.g. in "C:\cyclos_3.7").
  • Browse to this directory and run the start script. In windows run the start_cyclos.bat by double clicking or run via de command prompt. In Linux or Mac you can run it via de command prompt.
  • When you see the message "Cyclos standalone server started at ...", open a web browser and go to the url http://localhost:8080 (this is the default setting).
  • Use the login name admin and the password 1234 to login Cyclos.
    • If you want to login as a member, you will need to create a member first, this is described below.
  • To shut down Cyclos close the console window.

Cyclos stand alone installation with MySQL

The stand alone installation will use the (embedded) HSQL database. If you want to use the stand alone installation as live version we recommend to switch to a MySQL database, this can be done in a few steps:

  • Install a mysql database (see Step 2: Install MySQL).
  • Open the file (found in "cyclos_version\web\WEB-INF\classes\").
  • Comment the HSQL entries by putting a # sign in front of each entry (everything under the title "HSQLDB (File mode)") and un-comment the msyql entries by delete the first # sign (everything under the title "MySQL"). Then configure the database name you created (cyclos on the example) on the property 'hibernate.connection.url' (if needed you can also specify the the password and username here).
  • When starting Cyclos, an initial database will be created (it is even possible to configure a complete system in this way and later copy the database to a real server, in backup and restore is described how to do this).

Note: More detailed information on the system configuration and other issues like SSL activation and upgrades can also be found at the basic installation documentation (below).

Standard installation

The basic installation package contains the binary, source code, all necessary libraries and the Cyclos documentation.

Installation requirements

  • Operation system: Any OS that can run the Java VM like Windows, Linux, FreeBSD, Mac.
  • Make sure you have at least 500Mb memory available for Cyclos (if the OS runs 64 bits, for 32bits 300Mb should be enough)
  • Java Runtime Environment (JRE), Java 6 or 7 is required;
  • Web server: Apache Tomcat 6 or higher
  • Database server: MySQL 5.1 or higher
  • Cyclos basic installation package
  • If you use the SMS module, make sure the Cyclos version is compatible with the version of the SMS module. (see compatibility list)

Step 1: Install Java

(You can skip this step if you have already installed Java 6 or 7)

  • Install a Java runtime environment (JRE), for example download the latest Java Development Kit (JDK):
  • Go to:
  • Install the program to <install_dir> (for windows users e.g. C:\Program Files\Java\jdk1.6.0_21).
  • Make sure your system knows where to find JAVA, in windows you should make an environmental variable called "JAVA_HOME" which points to the <install_dir>:
    • In windows XP: configuration > System > advanced > environmental variables.
    • In windows 7: Control Panel > System and Security > System > Advanced system settings > Environmental Variables.
    • You can check if Java is installed correctly by typing "java -version" in the command line. This should display the version of Java you just installed.

Step 2: Install MySQL

(You can skip this step if you have already installed MySQL 5.1 or higher)

sudo apt-get install mysql-server
  • Install the mysql server. Some issues to remember:
    • Make sure to enable tcp/ip networking, otherwise Cyclos doesn't work.
    • Select "Multifunctional Database".
    • Support for Multilingualism is not needed, unless you want to develop in a language character set which is not supported by default.
    • The default account for root will do, there is no need to create an anonymous account.
  • You can check if the MySQL server is running by going to the command line and type (in this example the user name is root and the password is 1234):
mysqladmin -uroot -p1234 status

Step 3: Install Tomcat

(You can skip this step if you have already installed Apache Tomcat 6 or 7)

Note: Cyclos 3.5 only works with Tomcat version 6.0.20 or lower. Cyclos 3.6 works with Tomcat 6 or higher.

  • Extract the zipped tomcat file into a folder <tomcat_home>
  • Start tomcat: <tomcat_home>/bin/startup.bat (Windows) or <tomcat_home>/bin/ (Linux). You might need to give the startup script file execute permissions.
  • Go to http://localhost:8080/ and check if tomcat is working.
  • The default memory heap size of Tomcat is very low, we recommend to increase it see Memory (Tomcat / Java).
Note on UTF-8

If Cyclos will display UTF-8 content it might be necessary to add a line in (or catalina.bat for windows) for example just after the huge initial comment:

In linux:
export CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF-8"
In windows:
set CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF-8"

Step 4: Configure MySQL

First an empty MySQL database named cyclos has to be created. Then Cyclos needs to have access to the MySQL database. You can enter the root password in the file It is better to give Cyclos his own password to enter the cyclos3 database. This can be done as follows (in this example the root password is 1234, the username Cyclos will use is cyclos and the password Cyclos will use is cyclos1234).

mysql -uroot -p1234
Welcome to the MySQL monitor

mysql> create database cyclos3;
Query OK, 1 row affected (0.01 sec)

mysql> grant all privileges on cyclos3.* to cyclos@localhost identified by 'cyclos1234';
mysql> grant all privileges on cyclos3.* to cyclos@ identified by 'cyclos1234';

The repetition here is defensive programming in case someone messes with the host file or something.
For full details on user account management see: "MySQL User Account Management" in the MySQL manual. 
If you need some other local access you can put for example:
mysql> grant all privileges on cyclos3.* to cyclos@'192.168.1.%' identified by 'cyclos1234';

flush privileges; (Don't forget this)

Ctrl-D (linux) or msyql>exit (windows)
msyql> bye

Step 5: Install Cyclos

(Make sure tomcat is working on port 8080 of the local machine, if you don’t run Tomcat as root make sure that the user has write access to the webapps directory)

  • Download the latest version of Cyclos at
  • Unzip the into a temporary directory.
  • Browse to the temporary directory and copy the directory web and its contents into the webapps directory (<tomcat_home>/webapps) of the tomcat installation.
  • Rename this web directory to cyclos. This name will define how users access Cyclos. For example, if you run the tomcat server on the URL would be Of course it is also possible run directly Cyclos directly under the domain name. This can be done by extracting Cyclos directly in the root of the webapps directory, or putting an Apache web server in front.
  • In the file you can set the database configuration, here you have to specify the username and password (use the password you specified in step 4) e.g.:
hibernate.connection.username = cyclos
hibernate.connection.password = cyclos1234
  • In the same ( file you can also set the language, enable http and https (explained in detail below) and other optional configurations.

If you use the embedded mode to create a default database make sure that you select the language in which you want the database to be created. In case you want to create a language different then the default (English) the translation file must be complete.

Note: Cyclos has an option to create a default database with preconfigured SMS settings. This can save much configuration time. In order to create the database with pre configured SMS settings make sure to set the parameter `cyclos.embedded.sms.enable` in the file as `true`. The must be done before initiating Cyclos for the first time.

Step 6: Startup Cyclos

  • (Re)start tomcat:
    • Unix: /etc/rc.d/rc.tomcat stop /etc/rc.d/rc.tomcat start
    • Windows: use TomCat monitor
    • You can also start trough <tomcat_home>/bin/startup.bat (Windows) or <tomcat_home>/bin/ (Linux).
  • If you left the default "embedded mode" set to "true" a default (InnoDB) database will be created upon initialization.
  • When tomcat is started and Cyclos initialized browse to the web directory defined in step 5 (for the default this would be http://localhost:8080/cyclos)
  • You can login with user: admin password: 1234
  • Go to Settings: Local settings > Cyclos instance identification > 'Application root UR' and put the URL of your installation (same as specified above). This URL is used when generating e-mail notifications that contain links to the Cyclos installation. For example an e-mail asking for password confirmation with a link.

If you are using the default database you can have a quick view at the Cyclos functions by creating a member and a broker as follows:

  • Go to: "Users & Groups > Manage Members".
  • At "create new member" drop down menu you can select "full member" or "full broker".
  • This will open a profile registration page. Fill in the fields and select "Save and open profile".
  • In "Actions for Member" window select "Manage password" and set a new password.
  • Now you can login as the member or broker you just created.
  • But before you go live with the system it is preferable to go trough the configuration and setup to make sure the installation meets the requirements of your organization. The best start is to read first the administration manual and the help files carefully (when you are logged in Cyclos go to "Help > Manual"). More information can be found on the Setup & configuration page.

Step 7: Make sure the Tomcat and MySQL server use the same time zone

It is required, in order to keep consistency between the state in the web server and data that both use the same time zone. If you have, for example, tomcat running with GMT-5 and mysql with GMT-3, all dates will be skewed by 2 hours. Also, in this specific case, no users will be able to login, as the session timeout (say, 20 minutes) will be immediately expired.

To fix this, it is possible to pass a mysql command to set the same time zone as the tomcat server. For example, in, you can set the test query to something like:

hibernate.c3p0.preferredTestQuery = set time_zone='-5:00'

To be able to use time zone names, see [1], but basically, on a Linux system, you can run:

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

Also, Cyclos can use a time zone (set through local settings) which is independent of the one set on Tomcat.

Shared hosting

Here are some tips if you want to install and run Cyclos on a shared hosting service

  • Make sure you comply with the Installation requirements (e.g. minimal memory, supported versions of Java/Tomcat/MySQL)
  • Make sure the files are unpacked (unzipped) in a directory (not just uploading the war)
  • Make sure the user that runs tomcat has write permissions to that directory.
  • It is common that hosting companies that offer shared hosting have the Java security manager enabled. If so, the security manager needs to be configured (by the hosting company) to set the necessary permissions such as; read and write access to local files, open database connection, open e-mail server (smtp) connection. Here below a list with the necessary configurations:
grant {
  permission java.util.PropertyPermission "*", "read,write";
  permission "*:-", "connect,accept,listen"; //must check the instance name, here are using cyclos as instance name
  permission "${catalina.home}/webapps/cyclos/-","read,write,delete"; //must point to tomcat temp dir
  permission "${catalina.home}/temp/*", "read,write,delete";
  permission "${java.home}/lib/", "read";
  permission java.lang.RuntimePermission "setContextClassLoader";
  permission java.util.logging.LoggingPermission "control";
  permission java.awt.AWTPermission "*";
  permission "*";
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission "*";
  permission java.lang.RuntimePermission "*";
  permission "*";

Performance tips

  • If the instances use the same version you could move the libraries Cyclos uses cylos/WEB-INF/lib (except the cyclos.jar) to the shared tomcat/lib directory. This will reduce the memory.
  • In the file. Make sure to put the following value: hibernate.default_batch_fetch_size = 1 (previously it was set to 20, which is not necessary)

Note: If shared hosting does not work for you contracting a VPS (virtual private server) could be a good alternative. However, managing a VPS does require experience with system administration. Another option is cloud services for Java hosting such as Heroku and Jelastic. Once these services come available it will make the hosting of Cyclos considerably easier. Jelastic is currently in beta version but it is operational. It has an on-line interface that allows installing and running Cyclos with just a few clicks. A step by step installation manual can be found at this site. Jelastic offers for the moment the moment free hosting but this will change when they go live. If you know of any other Java hosting company that offers Cyclos hosting please let us know.

Advanced configuration & performance tuning

SSL activation

First you have to enable (un-comment) https in tomcat in the file <tomcat_home>/conf/server.xml

<Connector port="443" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" disableUploadTimeout="true"
    acceptCount="100" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS" />

For each cyclos instance on the server you can enable the http and https ports in the files of the instances.

### HTTPS configuration
# Enable HTTPS security
# HTTP port
# HTTPS port

Generate a key with the keytool from Java:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore

After executing this command, you will first be prompted for the keystore password. Passwords are *case sensitive*. You will also need to specify the custom password in the server.xml configuration file, as described later. Next, you will be prompted for general information about this Certificate, such as company, contact name, and so on. This information will be displayed to users who attempt to access a secure page in your application, so make sure that the information provided here matches what they will expect. Finally, you will be prompted for the key password, which is the password specifically for this Certificate (as opposed to any other Certificates stored in the same keystore file). You MUST use the same password here as was used for the keystore password itself. (Currently, the keytool prompt will tell you that pressing the ENTER key does this for you automatically). If everything was successful, you now have a keystore file with a Certificate that can be used by your server.

Connection pool (Cyclos)

In the WEB-INF/classes/ file you can modify the following sections:

### Connection provider properties (C3p0)
By default optimised for small to medium load (1-100 concurrent logged users)
For more information look at:
### Additional properties
By default optimised for small to medium load (1-100 concurrent logged users)

Memory (Tomcat / Java)

The default memory heap size of Tomcat very low. You can augment this by modifying the startup scripts in the /bin directory of Tomcat.
For windows in the file startup.bat

rem ----- Execute The Requested Command ---------------------------------------
set JAVA_OPTS= -Xms128M -Xmx512M -XX:MaxPermSize=128M

For Linux in the file

# ----- Execute The Requested Command ---------------------------------------
JAVA_OPTS="-Xms128m -Xmx512m -XX:MaxPermSize=128M"
echo "Using JAVA_HOME: $JAVA_HOME"
echo "Using JAVA_OPTS: $JAVA_OPTS"

Compress files (Tomcat / Apache)

Most browser support the compressing of files. As Cyclos has some large files compression will improve the download times considerably (up to five times). The tomcat project page explains how to enable compression.


If Apache is used in front of Tomcat you can enable compression by following the instructions of this site:



In the files my.cnf (Linux) or my.ini (Windows) you can put the following variables:

# Set buffer pool size to 50-80% of your computer's memory
# Set the log file size to about 25% of the buffer pool size

Note: For fine tuning of a clustered database environment please refer to page Clustering - MySQL

Useful commmands

Reset lost passwords

It might happen that the administrator login (and/or transaction) password is lost. In this case you can reset the password directly in the database. It can also be handy (especially for tests) to reset the passwords of all users in the system. Because from version Cyclos3.0 on the password hashing algorithm was changed (from MD5 to SHA2) and the SALT hashing was added it needs different commands. Below a explanation how to do this:

For Cyclos version 3.6.x migrated from Cyclos version 3.0

Set login password to 1234 and transaction password to abcd (if enabled) for all admins and members

update users set salt=null, password='fec4b44bf631dee30898d9570ae87f7f2a261780e0e261fef3f21985b6e36777', 
transaction_password='e51fdf5b1d1a18d3b82c516687f5f2a7b974565a71dfc9f516d8a90213cd66b5', transaction_password_status='A';

Set login password to 1234 and transaction password to abcd (if enabled) for admin only

update users set salt=null, password='fec4b44bf631dee30898d9570ae87f7f2a261780e0e261fef3f21985b6e36777', 
transaction_password='e51fdf5b1d1a18d3b82c516687f5f2a7b974565a71dfc9f516d8a90213cd66b5', transaction_password_status='A' where username='admin';

For Cyclos version 3.6 (not migrated from version 3.0)

Set login password to 1234 and transaction password to abcd (if enabled) for admin only

update users set salt=null, password='03ac674216f3e15c761ee1a5e255f067953623c8b388b4459e13f978d7c846f4', 
transaction_password='e12e115acf4552b2568b55e93cbd39394c4ef81c82447fafc997882a02d23677', transaction_password_status='A' where username='admin';

Set login password to 1234 and transaction password to abcd (if enabled) for admin and members

update users set salt=null, password='03ac674216f3e15c761ee1a5e255f067953623c8b388b4459e13f978d7c846f4', 
transaction_password='e12e115acf4552b2568b55e93cbd39394c4ef81c82447fafc997882a02d23677', transaction_password_status='A'; 


It is possible to run Cyclos in a clustered environment in order to provide high availability, redundancy and recovery for Cyclos hosting services.

Apache (Load balancer)

Apache will be used as load-balancer. The load balancer will distribute the requests to the tomcat servers. It is possible to define different loads per tomcat instance. Apache2 and modjk are required. For example, in Ubuntu, install the following packages: apache2 and libapache2-mod-jk. Setup a LoadBalancer worker, and each worker on /etc/libapache2-mod-jk/ Example:

# Declare Tomcat server workers 1 through n

# Associate real workers with virtual LoadBalancer worker

# Factors (higher means more priority)

On /etc/apache2/sites-enabled/XXX, add the following insite <VirtualHost>:

    <IfModule mod_jk.c>
        JkMount /cyclos/* LoadBalancer
        JkMount /cyclos LoadBalancer
        JkMount /jkmanager/* jkstatus
        JkMount /jkmanager jkstatus
        <Location /jkmanager>
            Order deny,allow
            Deny from all
            Allow from localhost

On /etc/apache2/httpd.conf (or at the end of /etc/apache2/apache2.conf) make sure the following is present:

    <IfModule mod_jk.c>
         JkWorkersFile /etc/libapache2-mod-jk/

Heartbeat service (failover)

As the LoadBalancer is a single machine, it would be a single point of failure if it crashes. However, it is possible to setup a failover machine which could take over the crashed server in case of failures. For this, Linux has the heartbeat service. It works by using a virtual IP address, which the LoadBalancer responds to. In case the main server stops responding to that IP (pings), the secondary server starts responding to that same IP address. Install the heartbeat package in both servers.

In both servers, configure /etc/ha.d/ like this:

logfacility local0 #used to tell heartbeat which log facility to utilize for logging
keepalive 2 #interval between heartbeat packets currently every 2 secs you could also use 2000ms
deadtime 5 #timeout before the other server takes over
ping #physical address of the other server
udpport 694 #port to listen in on for broadcasts made by heartbeat
bcast eth0 #device to use for broadcasts
node # dns name of the main server - should be the same as returned by `uname -n`
node # dns name of the failover server - should be the same as returned by `uname -n`
auto_failback on # very important or auto failover won't happen

Then, also in both servers, configure /etc/ha.d/haresources like this: IPaddr:: apache2

In this file, the host name is always the main server hostname (in both servers). The given IP address is the virtual IP address which will be used by clients. 24 is the netmask category (equivalent to To be sure which number is equivalent to your netmask, use Here, eth0 is the network device used for this network. Finally, apache2 (or an space separated list) is the service (or services) to be started by heartbeat when the fallback server takes over the main server.

In both servers, remove apache2 (and other services, if specified in haresources) from the system initialization:

update-rc.d -f apache2 remove.

Finally, you need, in both servers, the /etc/ha.d/authkeys file, which must be equals in both servers:

auth 1
1 md5 SomeLongPassword


ERROR: should_drop_message: attempted replay attack...

Solution: You probably cloned one machine from the other. Delete /var/lib/heartbeat/hb_uuid on either one of the machines and try again.

Tomcat (cluster node)

Please use Apache Tomcat 6.0.28 or higher.

When using cluster replication the users will not not loose their current sessions (they don’t even notice the server failure) in case a node fails. In order for this to work, on Tomcat’s server.xml, on the <Engine> tag, make sure to add a jvmRoute attribute with the same name as the respective worker (as defined in For example:

    <Engine defaultHost="localhost" jvmRoute="worker1" name="Catalina">

Also, inside the <Engine> tag, add the <Cluster> configuration, for example:

    <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" channelSendOptions="6">
        <Manager className="org.apache.catalina.ha.session.BackupManager"
        <Channel className="">
            <Membership className="org.apache.catalina.tribes.membership.McastService"
            <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
            <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
                <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
            <Interceptor className=""/>
            <Interceptor className=""/>
        <Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
        <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>

Make sure to setup as AJP port the same one as configured in An HTTP connector is optional.

Ensure that on machine hosts file there is a entry mapping the server hostname to the server real network ip. By default ubuntu comes with       localhost       ServerHostName

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

Note! You will need to change the loopback IP to your local network ip.

Note! If Cyclos will display UTF-8 this configuration might be necessary.



MySQL has a native cluster which uses the NDB (network database) storage engine. However, it would require several changes to Cyclos in order to support it. We chose not to implement NDB because it would limit Cyclos to support only MySQL NDB. With the current structure Cyclos can support other databases as well (e.g. the standalone uses HSQL). So, the options are either to use different cluster solutions or semi synchronous replication.

There are 3rd party forks of MySQL which does fully synchronous replication (clustering), like Galera Cluster for MySQL or commercial solutions like SchoonerSQL or Percona XtraDB Cluster. We did some initial tests with Galera, but didn`t finish configuring and subject it to more rigorous tests yet.

- Clustering will be generally less performatic (for writing operations) than solutions with semi-synchronous replication.
Be aware that to support fail-over it is usually a requirement to have a node in a different physical location. This means you need a very good and dedicated network (WAN) connection when using a cluster. (Galera has specific configurations for WAN traffic).
- Even in clustered environments. It is good practice (and relatively easy) to add a a-synchronous replication for backup purposes.
- In the multiple database (semi synchronous) option we suggested to run consistency checks. It is good practice for any large project to run such checks and implement follow up procedures. No matter what solution you chose.


Although replication does not fall in the scope of clustering, it can be an interesting solution for providing database fail-over (with semi-synchronous replication). Generally, replication will be easier and cheaper to setup than a full multi-master cluster (like Galera).

MySQL 5.5 introduced semi-synchronous replication, which guarantees that a successful return will involve a master commit and the data present in the relay log of at least one slave. The relay log is then copied, at a later time into the transaction log, making the data visible in the slave. When the slave detects that the master has been shutdown, it will stop accepting connections until the relay log is fully copied to the transaction log, guaranteeing that no stale data will be read.

It is recommended to setup both main and failover servers as a master-master replication. That way, Cyclos will always access the main server. But, if it fails, the failover will be used, and data will be written / read from it. At a later time, if the main server returns, it will automatically synchronize all new data on the failover server, and will be able to be used again by Cyclos.

Here is an example configuration for MySQL 5.5 for a master-master semi-synchronous replication:

Mysql configuration We need to: Load the required libraries for semi-synchronous replication. Create an user for the slave to connect. Configure the slave's master host and connection.

Run the following commands on mysql client (the user needs SUPER privilleges in order to be able to run them) for each host:

mysql> install plugin rpl_semi_sync_master soname '';
mysql> install plugin rpl_semi_sync_slave soname '';
mysql> grant replication slave,super,reload on *.* to 'username'@'%' identified by 'password';
mysql> change master to master_host='Host of the master', master_user='username', master_password='password';
On /etc/mysql/my.cnf, under [mysqld], configure on each host:
server-id		     = 1  # should be unique for each server
log_bin			     = mysql-bin
binlog_format                = MIXED
binlog_ignore_db             = mysql
binlog_do_db                 = cyclos3 # comma-separated list of databases to replicate
replicate-do-db              = cyclos3 # comma-separated list of databases to replicate
auto_increment_increment     = 2 # For two servers. This is like to permanently restrict the max number of servers.
auto_increment_offset        = 1  # each server should have a distinct offset
replicate-same-server-id     = 0
rpl_semi_sync_master_timeout = 10000
slave_exec_mode = IDEMPOTENT

Also, in /etc/mysql/my.cnf, make sure to comment the bind-address =, or connections from other hosts won’t be accepted.

Restart the servers.

Verify that the replication is working

mysql> show slave status\G
mysql> show variables like 'rpl_semi_sync%';

Heartbeat configuration

To switch to a failover host a tool such as heartbeat can be used. For installation and configuration follow this link omitting the apache configuration.

The only different (but very important) configuration is:
In /etc/ha.d/
auto_failback off # when off, heartbeat will not fail back when detects the master back. It will fail back when slave goes down. 
The fallen master has to be synced with the slave to be ready.


Cyclos keeps some local resources (like caches and local files) and runs scheduled tasks (that should be run only once every hour). When running in a cluster, we need some way to synchronize those, otherwise, for example, changing a customized file or a translation key in one server in a cluster would not affect the other servers. For the synchronization in the cluster, we use Hazelcast ( Hazelcast also provides a second level cache provider for Hibernate, but we don’t use it. That’s because the distributed Map that Hazelcast uses targets very large clusters, and don’t have the data replicated in all nodes. Each node owns parts of the data, and this could generate extra network traffic on Cyclos. Instead, we use EhCache, which keeps a local copy of all cached data, but we’ve created a replicator for EhCache using Hazelcast. So, we don’t need to setup another clustering library (like Terracota or JGroups which JGroups support by default). In order to enable Hazelcast in Cyclos, 2 files must be touched: ehcache.xml and In Cyclos, all components which are currently using Hazelcast are actually pluggable (so, depending on specific needs, a different clustering tool could be used).


<ehcache xmlns:xsi="" xsi:noNamespaceSchemaLocation="../config/ehcache.xsd">
</ehcache> Enable Hibernate second level cache and disable query cache:

hibernate.cache.use_second_level_cache = true
hibernate.cache.use_query_cache = false

Note: The use of hibernate query cache isn't supported for cluster environments

Set each pluggable component to use Hazelcast:

cyclos.instanceHandler = nl.strohalm.cyclos.utils.instance.HazelcastInstanceHandler
cyclos.taskRunner = nl.strohalm.cyclos.utils.tasks.HazelcastTaskRunner
cyclos.customizedFileHandler = nl.strohalm.cyclos.utils.customizedfile.HazelcastCustomizedFileHandler
cyclos.uniqueHandler = nl.strohalm.cyclos.utils.lock.HazelcastUniqueObjectHandlerImpl

If using a replicated MySQL for HA, change the jdbc url:

hibernate.connection.url = jdbc:mysql://host1,host2/cyclos3?autoReconnect=true

Or: If using a replicated MySQL with load balancing (poses a risk, as discussed previously), do this:

cyclos.lockHandlerFactory = nl.strohalm.cyclos.utils.lock.HazelcastLockHandlerFactory
cyclos.lockHandler.timeoutSeconds = 3
hibernate.connection.url = jdbc:mysql://host1,host2,hostN/cyclos3?autoReconnect=true

Configuring hazelcast.xml
Hazelcast can be configured with the hazelcast.xml file, which is located in WEB-INF/classes. All available configuration options are available described on [2]. For Cyclos, the most relevant configuration are:

  • The Hazelcast group username / password. If you have multiple Cyclos instances in the same local network, each should group use distinct username / passwords. For all Cyclos instances of the same cluster, both username and password should be identical.
  • The network configuration: Here it is possible to change the listen port and also the connection mode. The default is UDP multicast, but can be configured as tcp-ip as well, by assigning a list of other cluster nodes. The cluster will be reacheable through any node - there is no need to put here the addresses of all cluster nodes.
  • The backup count for the cyclos.initializationControl and cyclos.scheduledTaskControl maps: Hazelcast distributes data along the cluster, so if all nodes owning copies of a particular data are down, that data will be lost. Those 2 maps are essential to control the lifecycle of the entire cluster, and it is important to have some backup copies configured.


In order to monitor and (auto) restart services the MONIT service can be used. A typical system would monitor Apache, Tomcat and MySQL.

Setup examples

We have defined three levels of ‘best practice’ installation setups for Cyclos hosting. The examples are described below.


Simple setup

All services are installed on a single server with an online (asynchronous) backup of the database. Usually the backup database is hosted at a remote server. Using a dedicated server for one Cyclos instance would offer sufficient performance for most business networks (see performance test results below) The major drawback of the simple setup is that it does not provided (automatic) fail-over / continuous availability.


Medium setup

Projects that need high availability and redundancy (fail over) can implement the medium structure. In this setup Cyclos is run in a Tomcat clustered environment and the database is run on two servers with semi-synchronous replication. All though the database is replicated (master-master) the Tomcat cluster will only access one database because of possible of the credit limit issue described in the Cyclos section above. For backup the master database can be replicated to a remote database using a-synchronous replication.

With a typical use of the Cyclos software the load of the Tomcat would demand four to five time more resources than the Database. Therefore we assume that having four or five Tomcat servers (in cluster mode) and one MySQL database with fail over (using semi-synchronous replication) would offer sufficient performance and fail-over for medium to large networks.


Advanced setup

For very large networks the advanced structure can be used. The examples of the advanced setup have the same logical structure. The main difference is that the Apache load balancer is running on dedicated servers and the MySQL database can be clustered (example advanced2).

Security considerations

Network security

For high security the load balancer, tomcat, database, and the administration access server (if used) could be placed on separate local IP networks secured by firewalls. (In order to keep the diagrams simple we did not include firewalls. Where and how to implement firewalls is straightforward for any network specialist).

Enabling secure https

In the file https can be enabled. You will need to get a certificate for the domain Cyclos is running on.

Admin IP whitelist

A part from the permissions check it is also possible to restrict administration access by IP or domain. This can be done enabling a white list for administration access (see Cyclos admin section - Settings - Access settings).

Restricting group access

Another extra level of security can be implemented by defining in the file what groups can and cannot access a particular Cyclos instance. This is of course only applicable if there is more than one Cyclos (tomcat) instance connecting to the same Cyclos database. The file has a white-list and blacklist option that can contain cyclos groups (member/broker/admin).


The group access white/black list option for instances can be used to implement a very high level of security. A separate Cyclos instance could be configured as unique access point for administrators. All other instances could be restricted to member/broker access only. Member of these groups won’t be able to access the administration section, even if their IP/domain is listed in the white list of the Cyclos access settings. The ‘administration’ instance would access the same Cyclos database as the other instance(s). In the case of a clustered setup the administration instance would run outside the Cyclos cluster but should use the hazelcast replication.

Cyclos security layer

For any operation done in Cyclos there is a check if the logged user has the correct permissions to access the data. Permissions are always double checked, in the presentation layer as well as the business logic layer.

Cyclos security configuration

Cyclos has many security options that can be enabled by configuration. For example enabling stronger password policies, virtual keyboard for password input, kaptcha image on registration, additional transaction password, authorization for payments, and administration alerts on suspicious behaviour.

Performance testing

Follow this link: Performance_testing to find out about the tests that have been made.



All data in Cyclos is stored in the database. Making a backup of the database can be done using the msyqldump command (MySQL) or copying the ‘Data’ folder (HSQL). The only file that you need to back-up (only once) will be the configuration file. If you made your own customized ‘theme’ and this one is not part of the Cyclos release you have to backup this too. The themes are located in the WEB-INF\themes directory and have a .theme extension. You can export a theme from the administration section: "Content Management > Themes > Export current settings as theme" (if you made a nice one, please send it to us so that we can include it in the next release).

The database can be backup-ed manually as follows (in this example the name of the database is cyclos the username root and the password 1234):

mysqldump -uroot -p1234 cyclos > cyclos.sql


If you want to start using cyclos with the data from a backup. You can just import the backup-ed database (in this example the name of the database is cyclos the username root and the password 1234 the name of the backup is cyclos.sql make sure to specify the path if your not in the same directory as the file):

mysql -uroot –p1234 cyclos < cyclos.sql

Cyclos dump without images

This might be handy for trouble shooting large databases (in this example the name of the database is cyclos the username root and the password 1234):

mysqldump -uroot -p1234 cyclos --ignore-table=cyclos.images > cyclos.sql (where cyclos is the database name)
mysqldump -uroot -p1234 cyclos --no-data --tables images >> cyclos.sql 
(this is an append with an empty table, without the table it won't start)


To know what package to use you will need to check (in the changelog) if there are new libraries. If not you can just use the upgrade package (cyclos_versionnr_upgrade.war) which contains the Cyclos binary code but not the third party libraries. Therefore the size of this package is relatively small (around 5Mb). Normally this is the only package that is needed for an upgrade of Cyclos. In the 'Docs' directory you can find the change log that lists the new features, bugfixes, new or changed third party libraries and the names of new translation files and keys.

The upgrade package has only a renamed version of the file ( This way your file will not be overwritten when you copy the new deploy over the current one.

The upgrade of the database is done automatically if the setting in the configuration file is set as follows:

### Automatically apply schema upgrades for new versions
cyclos.autoSchemaUpgrade.enable = true

This is set by default so if you did not changed this upgrading to a new version of Cyclos will automatically upgrade the database (but leave the current database entries intact).

Upgrade steps

  • Stop Cyclos.
  • Backup ${CATALINA_HOME}/webapps/cyclos.
  • Switch to the Tomcat webapps Cyclos folder:
cd ${CATALINA_HOME}/webapps/cyclos/
jar xf cylcos_3.X_upgrade.war
  • Start Cyclos.

Custom installations

Installation on Gentoo (using mod_proxy_ajp to make it accessible on port 80)

This was my experience installing Cyclos -a complementary currency system- on Gentoo using mod_proxy_ajp to make it accessible on port 80.

software versions used: apache-2.2.8 tomcat-6.0.16 cyclos-3.0.8

First thing I had to do on my box was upgrade apache from 2.0 to 2.2 so that I could use mod_proxy_ajp. If you need to do this too, take your time to read the docs at Gentoo and

There are many differences between both versions so you will need to modify many config files by hand in order to get it working. Double check that you are building apache with all the necessary modules.I

If you are lucky and you already have 2.2 running, next thing is:


# emerge tomcat

As you will see in the post-install notes, Gentoo installation of Tomcat is somewhat heterodox as it tries to comply with the FHS layout and thus does not install everything under /opt as is usual with this package on other distros.

You should read the Tomcat Gentoo guide at this point.

In my particular case I needed tomcat to run on a different port than 8080 because I'm already using that one for Zope. If this is your case, you'll need to edit the /etc/tomcat-6/server.xml file and replace any occurrences of 8080 for 8090 or whatever port number you choose.

With your tomcat install in place it's now time to download cyclos itself. It's available at the sourceforge download page for the project. The most current version at the moment of this writing is 3.0.8. You should get the file, not the standalone if you are planning to run it with this tomcat/apache setup. In Gentoo, tomcat webapps are installed under the /var/lib/tomcat-6/webapps/ directory, so you should unzip the file you downloaded to some temporary folder and copy the extracted web/ directory to your /var/lib/tomcat-6/webapps folder. Rename web/ to whatever you please, I just named it cyclos. Remember also to set the ownership of this folder and it's content to tomcat:


# chown tomcat:tomcat /var/lib/tomcat-6/webapps/cyclos -R

Next thing you'll need to do is edit the WEB-INF/classes/ file. It's important here that you change the 8080 port to whatever port you've configured tomcat to run at. In my case:


You also need to set the url (which depends on what you renamed the web/ directory to). In my case the line reads:


And the database data needs to be set to whatever your configuration will be. I'm using mysql, so under the ###MySQL section I had to change these lines:


hibernate.connection.url = jdbc:mysql://localhost/cyclos
hibernate.connection.username = cyclos
hibernate.connection.password = your_password_here

In this version of cyclos the database name came for some reason set to puntotransacciones, which as you can see I've changed to cyclos.

Done with the editing.

If you haven't set up your MySQL database yet, now is the time. Create a database called cyclos (or whatever you've used in the properties file) and grant all privileges on it to cyclos@localhost user like so:


mysql> create database cyclos;
mysql> grant all privileges on cyclos.* to cyclos@localhost identified by 'your_password_here';
mysql> flush privileges;
mysql> Ctrl-D  to exit

Everything is in place. You should now start or restart your tomcat service:


# /etc/init.d/tomcat start

Don't forget to add the service to your default runlevel so it gets started when the server reboots.


# rc-update add tomcat-6 default

You are all set now to try cyclos on port 8090 (or whatever port you have chosen). Point your browser at http://localhost:8090/cyclos or at your server's public IP:8090/cyclos

If you don't get the cyclos login page something has gone wrong. You should check your log files at: /var/log/tomcat-6/localhost.CURRENT_DATE.log

First thing to check is that tomcat is effectively running on port 8090. Point your browser at http://localhost:8090/ to check this.

If tomcat is running you can use the manager tool to start and stop webapps. The manager tool is available under Administration in the left hand panel of the standard tomcat welcome page. In order to be able to login you'll need to edit /etc/tomcat-6/tomcat-users.xml and add a user so you can log-in. My file looks like this after editing:


<?xml version='1.0' encoding='utf-8'?>
<role rolename="manager"/>
<role rolename="standard"/>
<user username="your_username" password="your_password" roles="standard,manager"/>

I restarted tomcat after editing the file, but don't know if it's necessary.

Once you log in to the Tomcat Manager you'll see your cyclos webapp listed and it's current status.

I find it helpfull to run on a ssh terminal:


# tail -f /var/log/tomcat-6/localhost.2008-05-25.log

while on the manager interface I try to start the cyclos webapp.

This will show in real time what's going wrong with the setup. In my case the problem was that I had left the database name line unchanged in the file and so my log showed that the cyclos user was unable to open the puntotransacciones database :) Of course YMMV here.

Once everything is working well on port 8090 all you need to do is add some lines to your VirtualHost on apache to have it redirect requests to tomcat using mod_proxy_ajp. You can read about it in this howto. All I had to do is edit /etc/apache2/vhosts.d/ (you should change this to the domain you'll be using) and add the following lines inside de VirtualHost section:


ProxyPass /cyclos ajp://
ProxyPassReverse /cyclos ajp://

You should check that you are loading the proxy module for apache. In your /etc/conf.d/apache2 file you should add -D PROXY to the APACHE2_OPTS values.

Restart apache and that's it. The cyclos instance is now available at

If you are planning to run more than one instance of cyclos on the same server you'll need to make as many copies of the original web/ folder you extracted from under your webapps directory. You'll have to adjust the file in each instance to reflect the URL/folder and the database configuration data. You should create as many databases as cyclos instances you'll be using. And last but not least, you will need to tune the amount of RAM that is assigned to tomcat by modifying the file /etc/conf.d/tomcat-6 and adding the line:



Or whatever amount of RAM you need. I'm running three instances and 96Mb seems to be the minimum amount to have the three of them started. Once again the Tomcat Manager is your friend if you need to see what instances have been started and which haven't. Read the logs to find out what's happening. If the amount of RAM is too small you'll see a message saying something like: Quote: Invocation of init method failed; nested exception is java.lang.OutOfMemoryError: Java heap space

Increase the amount of memory by changing the -Xmx value, restart tomcat and try again.

You may also add the corresponding directives to your vhost in apache. In my case I have: Quote:

ProxyPass /cyclos_testing ajp://
ProxyPassReverse /cyclos_testing ajp://

ProxyPass /cyclos_demo ajp://
ProxyPassReverse /cyclos_demo ajp://

Doing this will give a warning on apache start and stop because we are using the same context and JVM on port 8009 for the three instances. I'm using this setup but still don't know if the warning is important or not. Time will say i guess! If you wish to explore this subject you may find this document - section Configuring for Multiple Tomcat JVMs- enlightening.

If you find any mistakes in this simple guide please let me know on the corresponding Gentoo forum thread so I can correct them.

Good luck and happy local trading :)