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 start with preparing database (it will be populated by Cyclos automatically), then proceed with Cycols setup and finally discuss SMS module installation.
1. Login to cPanel and find ‘MySQL Databases’ in Databases section. Click it to proceed with database creation.
2. Fill in database name suffix. Note that your database name will always begin with ‘username_’ prefix.
3. Create database user. Again, its name will start with ‘username_’ prefix. Save password for later use.
4. Assign the user to the database. Users sometimes forget about this third and required step when setting up databases in cPanel.
5. 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.
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
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:
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?
You will first need to order dedicated IP addon so that SSL certificate (commercial or self-signed could be setup). Our support will 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).
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
Heap and non-heap JVM memory usage with Apache Tomcat and idle or lightly used Cyclos is show below.
If you set ‘cyclos.embedded.sms.enable = true’ 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):
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
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
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 end of 2013 and will be 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.