1. Installation & maintenance
Prev   Next

1. Installation & maintenance

This is the installation manual for Cylcos 4 PRO. Be aware that Cyclos is server side software. End users (customers) will be able to access Cyclos directly with a webbrowser or mobile phone. If you have any problems when installing Cyclos using this manual, you can ask for help at our forum.

Cyclos can be installed on a tomcat server or inside a docker container. If you want to have a quick preview of Cyclos it is easier to use the docker container (especially on Linux). Chapter "Install Cyclos using Tomcat" explains how to install Cyclos using a normal tomcat server and chapter "Install Cyclos as a Docker image" explains how to install Cyclos using docker.

1.1. Install Cyclos using Tomcat

1.1.1. System requirements

  • Operation system: Any OS that can run the Java VM like Windows, Linux, FreeBSD or 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 8 is required;
  • Web server: Apache Tomcat 7 or higher;
  • Database server: PostgreSQL 9.3 or higher;
  • Cyclos installation package cyclos_version_number.war;

1.1.2. Install Java

You can check if you have Java installed at this site: http://java.com/en/download/installed.jsp If you don't have Java 8 installed proceed with the steps below:

Linux (Ubuntu)

  • Install the openjdk-8-jdk package.

Windows

  • Download and install the last Java SE Development Kit 8 (JDK8), e.g.: jdk-8uxx-xx-xx.exe
  • Install the program to <install_dir> (for windows users e.g. C:\Program Files\Java\jdk1.8.x_xx).
  • 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 Variable
    • In case you have different java versions installed make sure the PATH, CLASSPATH and JAVA_HOME point to the right place, click here for more information.
    • You can easily test if everything is set right by executing the following commands in command prompt: 
      echo %CLASSPATH%
      echo %PATH%
      echo %JAVA_HOME%

1.1.3. Install PostgreSQL (database)

Windows

  • If using Windows, download the latest version of PostgreSQL and PostGIS:
  • Install both PostgreSQL and PostGIS by following the installer steps (use the default options).
  • Make sure the bin directory is included in the system variables so that you can run psql directly from the command line:
    • Go to: "Start > Control Panel > System and Security > System > Advanced system settings > Environment Variables…".
      • Then go to the system variable with the name "Path" add the bin directory of PostgreSQL as a value, don`t forget to separate the values with a semicolon, e.g.:
        • Variable name: Path
        • Variable value: Enter here the bin folder in Postgres installation folder, e.g.: C:\Program Files\PostgreSQL\9.4\bin;
  • Go to the windows command line and type the command (you will be asked for the password you specified when installing PostgreSQL): 
    psql -U postgres
  • If you see "postgres=#" you are in the PostgreSQL command line and you can follow the instructions: Setup cyclos4 database (common steps for windows and Linux).

Linux

  • If using Ubuntu Linux, these instructions are followed, type the following commands in a terminal:
  • Install PostgreSQL and PostGIS (using the official PostgreSQL packages for Ubuntu) 
    echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" \
| sudo tee /etc/apt/sources.list.d/postgresql.list
    wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
    sudo apt-get update 
    sudo apt-get install postgresql-9.4 postgresql-contrib-9.4 postgresql-9.4-postgis-2.1 \
postgresql-9.4-postgis-2.1-scripts
  • Access the postgresql command line: 
    sudo -u postgres psql
  • If you see "postgres=#" you are in the PostgreSQL command line and you can follow the instructions below.

Setup cyclos4 database (common steps for windows and Linux)

  • Create the user cyclos with the password cyclos. This password and username you will have to enter in the cyclos.properties file in step 5, so if you do not use the cyclos as password and username please write them down. Type in the PostgreSQL command line: 
    CREATE USER cyclos WITH PASSWORD 'cyclos';
  • Create the database cyclos4, type in the PostgreSQL command line: 
    CREATE DATABASE cyclos4 ENCODING 'UTF-8' TEMPLATE template0;
  • Make sure the user cyclos can use the database cyclos4, type in the PostgreSQL command line: 
    GRANT ALL PRIVILEGES ON DATABASE cyclos4 to cyclos;
  • Create the PostGIS and unaccent extensions on the database, type in the PostgreSQL command line: 
    \c cyclos4
create extension cube;
create extension earthdistance;
create extension postgis;
create extension unaccent;
  • Exit the PostgreSQL command line by entering "\q" (and pressing enter).

1.1.4. Install Tomcat (web server)

  • Download Tomcat (7.0.x core) at http://tomcat.apache.org/
  • Extract the zipped tomcat file into a folder <tomcat home>.
  • Start tomcat: <tomcat home>/bin/startup.bat (Windows) or <tomcat home>/bin/startup.sh (Linux). You might have to give the startup script file execute permissions.
  • Open a browser and go to http://localhost:8080/ and check if tomcat is working.
  • The default memory heap size of Tomcat is very low, we recommend increasing it (see adjustments).

1.1.5. Install Cyclos

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

  • Download the latest version of Cyclos from the license server. To download Cyclos from the license server you first have to register on the license server. Registrering at the license server allows you to use the free version of Cyclos. Please write down the loginname and password you chose when registering for the license server (it will be needed later on).
  • Unzip the cyclos-<version>.zip into a temporary directory.
  • Browse to the temporary directory and copy the directory web (including 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 www.domain.com the URL would be http://www.domain.com/cyclos. Of course it is also possible to run 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 folder <tomcat_home>/webapps/cyclos/WEB-INF/classes you'll find the file cyclos-release.properties. The first thing to do is to copy this file and give it the name cyclos.properties. The original name is not shipped, so in future installations you can just override the entire folder, and your customizations won't be overwritten.
  • In the cyclos.properties file you can set the database configuration, here you have to specify the username and password, by default we use 'cyclos4' as database name and 'cyclos' as username and password.* 
    cyclos.datasource.jdbcUrl = jdbc:postgresql://localhost/cyclos4
cyclos.datasource.user = cyclos
cyclos.datasource.password = cyclos

* Some systems do not resolve localhost and the default postgress port directly. In case of database connectivity problems you might try a URL: cyclos.datasource.jdbcUrl = jdbc:postgresql://local_ip_address:postgressport/cyclos4 example: cyclos.datasource.jdbcUrl = jdbc:postgresql://192.168.1.1:5432/cyclos4

** Windows might not see linebreaks in the property file, if this is the case we advice you to download an more advanced text editor such as Notepad++.

*** In windows problems might occur in the Cyclos versions 4.1, 4.1.1, 4.1.2 and 4.2. It can help to set the cyclos.tempDir variable manual. Point it to the temp directory inside the WEB-INF directory in Cyclos. E.g. "cyclos.tempDir = C:\Program Files\Tomcat7\webapps\cyclos\WEB-INF\temp". In some cases even forward slashes need to be used.

1.1.6. Startup Cyclos

  • (Re)start tomcat:
    • Unix: /etc/rc.d/rc.tomcat stop /etc/rc.d/rc.tomcat start
    • Windows: use TomCat monitor (available after tomcat installaton
    • You can also start trough <tomcat_home>/bin/startup.bat (Windows) or <tomcat_home>/bin/startup.sh (Linux).
  • 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). Be aware starting up Cyclos for the first time might take quite some time, because the database need to be initialized. On slow computer this could take up to 3 minutes!
  • Upon the first start of Cyclos you will be asked to fill in the license information.
  • After submitting the correct information, the initialization process will finish, and you will automatically login as (global) admininstrator.

1.1.7. Upgrading Cyclos

  • To upgrade Cyclos follow these steps:
    • Before updating always study the release notes and changelog they are published on the Cyclos license server.
    • Make a backup of the database.
    • Download the latest version of Cyclos from the license server.
    • Unzip the cyclos-<version>.zip into a temporary directory.
    • Browse to the temporary directory and rename the directory web to cyclos.
    • Copy your current cyclos.properties file (<tomcat_home>/webapps/cyclos/WEB-INF/classes/cyclos.properties) to the same place in the temporary directory.
    • Remove the directory cyclos from the tomcat webapps directory (<tomcat_home>/webapps/cyclos/).
    • Browse to the temporary directory and copy the directory cyclos (including its contents) into the webapps directory (<tomcat_home>/webapps) of the tomcat installation.
  • We would also recommend to do the following:
    • Between major Cyclos versions the Cyclos API can change, please test on a local server (with the database backup) if all scripts and extensions made through the web services still work.
    • In general it is a good practice to test everything before upgrading, if you test with your local database please don't forget to remove the email host and sms gateway so that the users don't receive any notifications.
    • All API changes per version can be found here: http://www.cyclos.org/documentation (see Webservices API Differences and Scripting API Differences).
    • If locally everything works fine a live update can be done as described above.
    • To avoid overwriting the cyclos.properties file without intention this file is named as cyclos-release.properties in the zip file. It might be interesting to study the new file to see if new settings have become available.
  • Upgrading to version 4.4.x or higher:

1.1.8. Problem solving

  • Often problems can be easily detected by looking at the log files, the log files of tomcat can be found in the logs folder inside tomcat. There are two relevant log files:
    • The Catalina log shows all relevant information about the tomcat server itself.
    • The Cyclos log shows all relevant information about the services and tasks that run in Cyclos.
  • If the logs can't help you to pin down the problem, you can search the Cyclos forum (installation issues) if somebody encountered a similar problem.
  • If this still has no results, you can post the (relevant) part of the logs to the Cyclos forum (installation issues), together with a description of the problem.

An example of an error that sometimes occurs is "WARN RequestContextFilter – Couldn’t write on the temp directory". In this case the user that started tomcat doesn’t have the write permission. This can be modified in Linux by executing the following commands as root (normally the name of the user is tomcat): 

chown -R tomcat /var/lib/tomcat7/webapps/cyclos
chmod -R 755 /var/lib/tomcat7/webapps/cyclos

In case you locked yourself out of the system, see paragraph "Maintenance" for how to reset the admins password.

Prev   Next
 Home 1.2. Install Cyclos as a Docker image