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 1GB memory available for Cyclos;
Java Runtime Environment (JRE), Java 11 is required;
Web server: Apache Tomcat 8.5 or 9.0. Tomcat 10+ implements Jakarta EE 10, which is not compatible;
Database server: PostgreSQL 9.6 or higher;
Cyclos installation package cyclos-version.number.zip;

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 11 installed proceed with the steps below:

Linux (Ubuntu)

Install the openjdk-11-jre package.

Windows

Download and install the last Java SE 11 or greater
Install the program to <install_dir> (for windows users e.g. C:\Program Files\Java\jre11).
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: 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 directory.
- 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)

Linux

If using Ubuntu Linux, these instructions are followed, type the following commands in a terminal:
Install PostgreSQL and PostGIS (Ubuntu 18.04 or greater)
```
sudo apt install postgresql postgis
```
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.

Windows

If using Windows, download the latest version of PostgreSQL and PostGIS:
- PostgreSQL: http://www.postgresql.org/download/windows (for example the graphical installer)
- PostGIS: http://postgis.net/windows_downloads (PostGIS can also be installed using the Stack Builder, that starts after PostgreSQL is installed. Also in this case use the default options.)
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).

Setup cyclos4 database (common steps for Windows and Linux)

Create a database user and password. This password and username you will have to enter in the cyclos.properties file in step 5. Type in the PostgreSQL command line:
```
CREATE USER cyclos WITH ENCRYPTED PASSWORD 'cyclos-password';
```

Create the database cyclos4, type in the PostgreSQL command line:

CREATE DATABASE cyclos4 ENCODING 'UTF-8' TEMPLATE template0 OWNER 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 (8.5 or greater) 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 the name that you will want to use at the URL, in this example we will use instance_name. 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/instance_name. There is some reserved words that cannot be used for the instance name,
The list of reserved words is:
```
cyclos.gwt
fonts
js
pay
consent
classic
ui
.well-known
robots.txt
sitemap.xml
sitemap-index.xml
sitemap.xstl
network-information-id.html
activate-access-client
external-redirect-callback
identity
run
content
web-rpc
java-rpc
api
sms
push-notifications
global
redirect
mobile-redirect
```
Of course it is also possible to run Cyclos directly under the domain name. This can be done by extracting Cyclos in the (<tomcat_home>/ROOT) directory (remove all files on it first), or putting an Apache web server in front of the Tomcat serer.
In the folder <tomcat_home>/webapps/instance_name/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. For production, it is recommended to change the 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 PostgreSQL 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, in case of problems, you can 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\Tomcat8.5\webapps\instance_name\WEB-INF\temp". In some cases even forward slashes need to be used.

1.1.6. Startup Cyclos

(Re)start tomcat:
- Stop trough <tomcat_home>/bin/stop.bat (Windows) or <tomcat_home>/bin/stop.sh (Linux).
- Start trough <tomcat_home>/bin/startup.bat (Windows) or <tomcat_home>/bin/startup.sh (Linux).
- Windows: you can use Tomcat monitor (available after tomcat installaton)
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/instance_name). 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.
- IMPORTANT! Make a backup of the database. New Cyclos versions generally contain new functionality that requires the database to be modified.
- 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 the instance_name.
- Copy your current cyclos.properties file (<tomcat_home>/webapps/instance_name/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/instance_name/).
- 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.
- 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.

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.
In case you locked yourself out of the system, see paragraph "Maintenance" for how to reset the admins password.
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, assuming a default Tomcat 9 installation in Ubuntu, which runs as the user tomcat9 and has /var/lib/tomcat9/webapps as web apps directory:
```
chown -R tomcat9 /var/lib/tomcat9/webapps/ROOT
chmod -R 755 /var/lib/tomcat9/webapps/ROOT
```
Another example that can occur if the server has crashed (the Tomcat service wasn't gracefully stopped) is the that your Cyclos database will be locked. This happens due to a feature we introduced in Cyclos 4.14.11 to prevent multiple Cyclos instances to connect to the same database (which can corrupt the data). This lock can be manually removed by running a SQL command in the database. For this, login to the Cyclos database (example: psql --user cyclos cyclos4), and run the following command:
```
delete from database_lock;
```