cyclos/cyclos repository overview

Docker image file for Cyclos 4.x (http://www.cyclos.org⁠)

What is Cyclos

Cyclos is a feature-rich online banking solution that is easy to use and maintain, flexible, secure and highly customisable.

Cyclos comes with a range of banking and payment options, a complete e-commerce system and high and low end mobile access channels. The mobile channel offers a scalable and cheap opportunity for banks to enlarge their outreach and to offer branchless banking.

Cyclos is used by local banks, C3 networks, MFI’s, barters, community currencies and time banks. The dynamic structure of Cyclos allows organisations to ‘build’ a dedicated payment system from scratch just by changing the configuration (without the hassle to make code changes).

Installing

First, make sure you have Docker 1.9+ installed. Please visit the following url and follow the instructions of how to install Docker: https://docs.docker.com/get-docker/⁠

After you have installed docker successfully you can install Cyclos by just executing 3 simple commands. The commands assume the Cyclos project is called cyclos. If desired, you can replace all occurrences of cyclos below to your project identifier. In Linux these commands can be executed directly from the terminal. Windows and Mac users need to start the Docker Quickstart Terminal. It is easiest to copy and paste the following commands, in windows right click the tile bar > edit > paste.

First create a (bridge) network in docker by executing the following command:

docker network create cyclos-net

Then create the database by executing the following command:

docker run -d \
    --name=cyclos-db \
    --net=cyclos-net \
    --hostname=cyclos-db \
    --restart=unless-stopped \
    -e POSTGRES_DB=cyclos \
    -e POSTGRES_USER=cyclos \
    -e POSTGRES_PASSWORD=cyclospwd \
    postgis/postgis

Finally install Cyclos and set the database:

docker run -d \
    --init \
    --name=cyclos-app \
    -p 80:8080 \
    --net=cyclos-net \
    --restart=unless-stopped \
    -e DB_HOST=cyclos-db \
    -e DB_NAME=cyclos \
    -e DB_USER=cyclos \
    -e DB_PASSWORD=cyclospwd \
    cyclos/cyclos

After a few minutes, Cyclos will have created the tables needed for the application, this will run on the background, so please be patient.

Startup

By default port 80 of the local machine will point to the application. If you have another server already listening on port 80, you can change this as needed, by changing the -p 80:8080 to -p 1234:8080, or whatever port you wish.

You can then open the URL http://localhost/⁠ (or http://localhost:1234/⁠) on your browser to open the first-time setup page. To continue, you will need to create a user on the Cyclos license page⁠. Cyclos is free for projects up to 300 users, as well as for social projects.

Upgrading from a previous version

Already created Docker containers are always kept in the same version. To upgrade Cyclos from a previous version, you will have to remove and re-create the application container. You may want to backup the logs before removing the container. See below on how to do this.

To upgrade, first you need to download the latest Cyclos image version to your local machine:

docker pull cyclos/cyclos

Then, remove the running application container, by running:

docker rm -fv cyclos-app

Finally, recreate the container using the same command as shown above, in the Installation section above.

Background

The Cyclos image is built over the official tomcat⁠ docker image.

The official PostGIS image is used as database. Then the Cyclos container can be linked with the database container, or both can share the same network. Custom networking is available from Docker version 1.9 onwards, and is recommended over linking.

For more information on how to configure Cyclos, please consult the online documentation⁠.

Checking for vulnerabilities

The Cyclos image is continuously scanned for security vulnerabilities. While some scanners may flag older Java libraries, we have manually reviewed and verified these findings. Most are marked as "Not Affected" in Docker Scout because the Cyclos team has reviewed its impact and asserts the vulnerable code paths are not reachable or utilized within Cyclos.

Additionally, the official Tomcat base image may contain Low or Medium OS-level vulnerabilities that do not impact the Cyclos runtime within the Docker container.

To view the actual security posture (excluding suppressed and base-image noise), you can run the following command using the Docker Scout CLI, replacing <version> with an actual version, such as 4.16.18:

docker scout cves cyclos/cyclos:<version> --org cyclos --ignore-suppressed --ignore-base

--

Stopping and starting the containers

Whenever you want to stop a running container, use the following:

docker stop cyclos-app cyclos-db

Similarly, to start it again, run:

docker start cyclos-db cyclos-app

To view the Tomcat standard output, run:

docker logs -f cyclos-app

This will block your console, and any new logging will be immediately visible. To exit, press Ctrl+C.

Backing up the database and logs

The database container is created (by default) without any port exposed on the host machine. To run an interactive psql command in the database, following the same example as above, where the database is called cyclos, run the following command in the host machine:

docker exec -it cyclos-db \
    psql --user cyclos cyclos

To perform a database dump to a file on the host machine, run the following:

docker exec -i cyclos-db \
    pg_dump --user cyclos cyclos > cyclos-dump.sql

You should find a file in the current working directory on the host file called cyclos-dump.sql.

Likewise, to restore a database dump from a file on the host machine, run the following:

docker exec -i cyclos-db \
    psql --user cyclos cyclos < cyclos-dump.sql

This assumes the database user and database are both cyclos and that there is a file in the current working directory on the host file called cyclos-dump.sql.

To backup the logs that Cyclos generates to files (and can be customized by Cyclos in the System > System configuration > Configurations menu), do the following:

docker exec -i cyclos-app \
    bash -c "cd /var/log/cyclos && tar -cz *.log" > logs.tar.gz

You shall find in the current working directory of your host system a file called logs.tar.gz, containing all log files that Cyclos has generated.

Exposing the AJP port for Apache httpd integration

If the Tomcat container is not supposed to be accessed directly by clients, instead, an Apache httpd⁠ front-end will handle request and forward them to Tomcat, then instead of mapping the port 8080 (HTTP) as the host port 80 (in the -p 80:8080 argument of the command above), you will have to map a port on the host computer to the port 8009 in the container. For example, with -p 8901:8009. In this example, the host port 8901 can be used by Apache's mod-jk to forward the requests.

Proxy / Load balancer

In some environments hosts are used to receive the client requests, and act as load balancers. They receive requests from clients and send a new request to Cyclos, sending the response back. The IP address that Cyclos receives is from the load balancer, not from the client. However, in those cases, normally the proxy also sends an HTTP header (normally X-Forwarded-For) with the original client IP address. As the sessions in Cyclos are restricted to the IP address, it is very important in these cases to set the cyclos.header.remoteAddress setting in cyclos.property, with the header name to be used to determine the real client IP address. See the next session on how to override a setting in the cyclos.properties file.

Overriding specific settings in cyclos.properties

To override specific settings in the cyclos.properties configuration file, you can set the JAVA_OPTS environment variable when starting the container, passing the specific property as a Java system property, in the format -Dcyclos.setting=value.

For example, to allow CORS⁠ from any website, do the following:

docker run -d \
    --name=cyclos-app \
    -p 80:8080 \
    --net=cyclos-net \
    --restart=unless-stopped \    
    -e DB_HOST=cyclos-db \
    -e DB_NAME=cyclos \
    -e DB_USER=cyclos \
    -e DB_PASSWORD=cyclospwd \
    -e JAVA_OPTS="-Dcyclos.cors.origin=*" \
    cyclos/cyclos

Configuring clustering

Starting with Cyclos 4.16, you can configure you cluster join strategy by setting specific environment variables. When any of these are found, Cyclos assumes cyclos.clusterHandler = hazelcast and replaces any <join> configuration in hazelcast.xml with the related strategy. The environment variables are described in the online documentation⁠.

Extending this image

You can create a custom Docker image based on this one. One of the reasons is to totally override the cyclos.properties file, or some other configuration file (hazelcast.xml or log4j2.xml).

To do this, create an empty directory, then create on it a file named Dockerfile with the following contents:

FROM cyclos/cyclos:latest
ADD cyclos.properties ${CYCLOS_HOME}/WEB-INF/classes

Then place in the same directory a cyclos.properties⁠ file, and customize it according to your needs. This can also be used to avoid using the DB_* environment variables when starting the Cyclos container, as those settings could be directly in the cyclos.properties file.

Other files that can be customized (don't forget to ADD them in the Dockerfile, just like the cyclos.properties example above):

• hazelcast.xml⁠: In case you have a cluster of Cyclos applications, they should synchronize state, and Hazelcast is used for this (set cyclos.clusterHandler = hazelcast in cyclos.properties). This file allows fine tuning many aspects of the cluster. If just to customize the Hazelcast cluster join strategy, we recommend using an environment variable instead of creating a custom image just for this. For more details, see the Installation & maintenance documentation⁠;
• log4j2.xml⁠: To set the log levels for logs generated on Tomcat's standard output.

Finally, build a Docker image. Keep in mind that the Cyclos Docker image is pushed with 2 architectures: linux/amd64 and linux/arm64. If you want to deploy to ARM servers, you probably need to use Docker buildx⁠, but it is out of context for this guide.

To build the image with the classic Docker build, within that directory, type:

docker build --pull -t cyclos-custom .

A Docker image will be created containing the changes. You need to create a container using the new docker image, replacing the cyclos/cyclos argument with cyclos-custom (or whatever name you gave to it), and the new settings will be applied. You probably have to remove the previous container with docker rm -f -v cyclos-app.

For more information on how to configure the cyclos.properties settings, and advanced configuration, like clustering (using Hazelcast to synchronize the cluster nodes) or storing files in the file system or Amazon S3 instead than on the database, please, consult the Cyclos reference documentation⁠.

More information

Please, refer to the Cyclos online documentation⁠, specially the Installation and Maintenance guide for more details on how to install and configure Cyclos.

Dockerfile for this image

For reference, in case you need to perform some additional customization in the container, it is always handy to know how the image was created. Here is the source of the Dockerfile, replacing @cyclosVersion with the actual version:

# Dockerfile for Cyclos project (http://www.cyclos.org)
FROM tomcat:9-jdk17-temurin
MAINTAINER Cyclos development team ([email protected])

# Environment setup
ENV CYCLOS_VERSION @cyclosVersion
ENV CYCLOS_HOME /usr/local/cyclos
ENV CYCLOS_LOGDIR /var/log/cyclos
ENV CATALINA_OPTS="--add-modules java.se \
    --add-exports java.base/jdk.internal.ref=ALL-UNNAMED \
    --add-opens java.base/java.lang=ALL-UNNAMED \
    --add-opens java.base/java.nio=ALL-UNNAMED \
    --add-opens java.base/sun.nio.ch=ALL-UNNAMED \
    --add-opens java.management/sun.management=ALL-UNNAMED \
    --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED"

COPY cyclos.war /tmp

RUN set -x && \
    apt-get update && apt-get install -y unzip ca-certificates openssl fonts-dejavu && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*
    
RUN set -x && \
    mkdir -p ${CYCLOS_HOME} && \
    mkdir -p ${CYCLOS_LOGDIR} && \
    unzip -o -d ${CYCLOS_HOME} /tmp/cyclos.war && \
    cp "${CYCLOS_HOME}/WEB-INF/classes/cyclos-docker.properties" "${CYCLOS_HOME}/WEB-INF/classes/cyclos.properties" && \
    rm /tmp/cyclos.war

# Change the workdir to CYCLOS_HOME
WORKDIR ${CYCLOS_HOME}

# Tomcat setup
RUN rm -rf /usr/local/tomcat/webapps/*
RUN ln -s ${CYCLOS_HOME} /usr/local/tomcat/webapps/ROOT
COPY context.xml /usr/local/tomcat/conf/context.xml

# Set the log dir as a persistent volume
VOLUME ${CYCLOS_LOGDIR}