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:
- Database setup
- Cyclos installation
- Optional Cyclos SMS module installation
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
- Login to cPanel and find MySQL Databases in Databases section. Click it to proceed with database creation.
- Fill in database name suffix. Note that your database name will always begin with username_ prefix.
- Create database user. Again, its name will start with username_ prefix. Save password for later use.
- Assign the user to the database. Users sometimes forget about this third and required step when setting up databases in cPanel.
- Check ALL Privileges on the next screen. You should now have the user displayed in USERS column besides your database in Current Databases table.
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
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.
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.
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. If
cyclos.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.