Published on Jun 28 2013 in

Cyclos is a popular Java based open source banking software. In this tutorial we show how to have it deployed in 5 minutes on JVM Host servers. This is step-by-step tutorial so everyone can easily use it.

As our application server we will use Tomcat 7. Tomcat Plus package from our offer is used. For production use we recommend Cyclos package that comes with 384MB of heap memory. We will use Cyclos 3.x.

The installation can be divided into 3 parts:

We will start with preparing database (it will be populated by Cyclos automatically), then proceed with Cycols setup and finally discuss SMS module installation.

Part I - Database Setup

You are done with the database part.

Part II - Cyclos setup

Let’s assume your hosting username is javauser. In this tutorial Cyclos will be installed as default web application and thus accessible at root URL like http[s]://javauser.jvmhost.net/. Of course you can use your own domain instead of an alias if you like. Alternatively you can just copy cyclos.war to webapps directory and have it reachable at http[s]://username.jvmhost.net/cyclos. Apache Tomcat 7.0.40 with JDK6 is used. Login to your account with SSH client and run the following commands:

cd && wget http://downloads.sourceforge.net/project/cyclos/Cyclos3/3.7.3/cyclos_3.7.3.zip
jk
rm -rf appservers/apache-tomcat-7.0.40/webapps/ROOT
unzip cyclos_3.7.3.zip 'cyclos_3.7.3/web/*'
mv cyclos_3.7.3/web appservers/apache-tomcat-7.0.40/webapps/ROOT

The above command set will download cyclos to your home directory, stop tomcat, remove existing default web application (webapps/ROOT), extract web app and copy it to webapps/ROOT and make some cleanup. Edit appservers/apache-tomcat-7.0.40/webapps/ROOT/WEB-INF/classes/cyclos.properties with an editor like mcedit, nano or vim and change below lines.

hibernate.connection.url = jdbc:mysql://localhost/javauser_cyc
hibernate.connection.username = javauser_cyc
hibernate.connection.password = the_password_you_set_in_part_I

Be careful about trailing spaces after password! None should be present. Optionally, if you intend to extend functionality with SMS module and want the application to create SMS related columns then set cyclos.embedded.sms.enable = true.

Alternatively you can simply paste the following stream editor commands into terminal:

cd appservers/apache-tomcat-7.0.40/webapps/ROOT/WEB-INF/classes
sed -i -e 's/cyclos3/javauser_cyc/' -e 's/root/javauser_cyc/' -e 's/password =.*$/password = the_password_you_set_in_part_I/' cyclos.properties
sed -i -e 's/sms.enable = false/sms.enable = true/' cyclos.properties

And you are done. Now start Tomcat with js and after a few seconds (Tomcat deploys Cyclos and the app creates tables in the database unless they already exist) access your website at http://javauser.jvmhost.net/. Access it with default user admin and password 1234.

Cyclos creating member

What if you need HTTPS?

Insrtall an SSL certificate (commercial or self-signed) in your cPanel then go to Java Control Panel - Mappings and clone existing HTTP mappings to HTTPS. Our support can help you with this. When it is completed then stop Tomcat with jk command or Java Control Panel and make the following changes in cyclos.properties (you can copy and paste below commands when logged in with SSH client).

jk
cd && cd appservers/apache-tomcat-7.0.40/webapps/ROOT/WEB-INF/classes
sed -i -e 's/^.*security.enable.*$/cyclos.security.enable=true/' -e 's/^.*port.http=.*$/cyclos.security.port.http=80/' -e 's/^.*port.https=.*$/cyclos.security.port.https=443/' cyclos.properties
js

Heap and non-heap JVM memory usage with Apache Tomcat and idle or lightly used Cyclos is show below.

Heap non-heap memeory usage of Cyclos with Tomcat

Part III - Optional Cyclos SMS module installation

Cyclos 4 comes with SMS support built-in but for Cyclos 3 you need to follow below steps. Ifcyclos.embedded.sms.enable = true was set above then tables in existing database will already have SMS related columns added. Create additional database in cPanel - you may name it as username_sms_aio (in our example javauser_sms_aio). Assign the existing javauser_cyc user to the database with ALL privileges. Then follow the Cyclos SMS configuration and also create 2 users in Cyclos that will be used for testing.

To install SMS module run the commands (replace database username/password and SMS database to match yours):

jk
cd && wget http://downloads.sourceforge.net/project/cyclos/SMS/1.2.2/cyclos3-sms_1.2.2.zip
unzip -o cyclos3-sms_1.2.2.zip &>/dev/null
mv cyclos3-sms_1.2.2/gateway ~/appservers/apache-tomcat-7.0.40/webapps/sms
cd cyclos3-sms_1.2.2/db
mysql -ujavauser_cyc -pthe_password_you_set_in_part_I javauser_sms_aio < driver/sms_driver.ddl
mysql -ujavauser_cyc -pthe_password_you_set_in_part_I javauser_sms_aio < controller/sms_controller.ddl
mysql -ujavauser_cyc -pthe_password_you_set_in_part_I javauser_sms_aio < controller/session_keys_en.dml
sed -i -e 's/cyclos3_sms_aio/javauser_sms_aio/' ~/appservers/apache-tomcat-7.0.40/webapps/sms/WEB-INF/classes/baseDriverConfig.properties
sed -i -e 's/db.connection.username=root/db.connection.username=javauser_cyc/' ~/appservers/apache-tomcat-7.0.40/webapps/sms/WEB-INF/classes/baseDriverConfig.properties
sed -i -e "s/db.connection.password=/db.connection.password=the_password_you_set_in_part_I/" ~/appservers/apache-tomcat-7.0.40/webapps/sms/WEB-INF/classes/baseDriverConfig.properties
cd && rm -rf cyclos3-sms_1.2.2
js

Note that the above command set installs SMS gateway application - we recommend you to first install simulator application as per instructions in SMS wiki to familiarize yourself with the config files.

Finally, you will need to confugure the module with a real SMS gateway and real phone number (we recommend nexmo.com as gateway). Follow Wiki instructions.

As virtual/digital currency system Cyclos is used by many organizations and communities to provide community currency services. It also allows to deploy mobile banking services: SMS banking and smartphone applications. Currently it supports ten languages but new languages are added with each release. Cyclos 4 PRO is to be realeased beginning of 2014 and is licensed version but fees will only be charged when the system exceeds a certain amount of users or generates enough profit. Version 3 will still be maintained.

Update: First Cyclos 4 PRO version is scheduled for February 2014. Licensing model allows for free usage of Cyclos 4 Pro with instances up to 300 users. Pricing list is here. We will happily deploy it for you on our VPS package and initialy configure with Euro currency and nexmo.com or other SMS gateway.

For more details and advanced configuration refer to comprehensive documentation.

Remember that if you do not want to install Cyclos 3 or 4 by yourself just let us know (open a ticket) and we will do it for you with pleasure.