This chapter describes how to install Convertigo Server in several qualified environments and operating systems.

This chapter describes how to install Convertigo Server in several qualified environments , operating systems , docker and Kubernetes.

General purpose and packages

Convertigo Server can be installed on different operating systems and application servers. The installation can be done on Windows or Linux operating systems and Kubernetes.

Convertigo Server installation is available as 2 packaging types :

  • convertigo-X.Y.Z.war file
  • docker images

Convertigo war file

Convertigo war file can be used with application servers in 64bits environments. It can be installed on Apache Tomcat. The minimum version of java must be 11, and for Tomcat 9.

The war file, convertigo-X.Y.Z.war, is available on

You can use java options to parameter Convertigo at run time.

Table 3 - 1: Specific java options for Convertigo

java option description
-Dconvertigo.cems.user_workspace_path Convertigo workspace path

More information on this parameter
-Dconvertigo.cems.global_symbols_file By default the symbols file is located in the <absolute_path_to_the_convertigo_workspace_directory>/configuration and is named With this option, it is possible to specify a different path and name.

More information on this parameter

All the configuration parameters in the Convertigo administration console can be set when launching Convertigo.
Find complete list of Convertigo Java System Properties on this link.

Convertigo docker images

Using docker images from Convertigo Docker Hub is the easiest way to install the server. By default you will use the official release but at any time you can point on pre-release or previous versions.

minimum Convertigo server

On a linux server with docker installed and running you can start a container with the minimum Convertigo server. Convertigo uses images/workspace directory to store configuration file and deployed projects as an docker volume.

$ docker run --name C8O -d -p 28080:28080 convertigo

You can access the server admin console on http://[dockerhost]:28080/convertigo and login using the default credentials: admin / admin

If you need fullsync functions, Convertigo FullSync module uses Apache CouchDB as NoSQL repository. You can use the couchdb docker image and link to it Convertigo this way:

Launch CouchDB container and name it fullsync

$ docker run -d --name fullsync couchdb:2.3.1

Then launch Convertigo and link it to the running fullsync container. Convertigo server will automatically uses it as its fullsync repository:

$ docker run -d --name C8O --link fullsync:couchdb -p 28080:28080 convertigo

MySQL is the recommended database for holding Convertigo server analytics. You can use this command to run Convertigo and link it to a running MySQL container. Change [mysql-container] to the container name, and [username for the c8oAnalytics db], [password for specified db user] with the values for your MySQL configuration.

$ docker run -d --name C8O --link [mysql-container]:mysql -p 28080:28080                             \
-e JAVA_OPTS="-Dconvertigo.engine.billing.enabled=true                                           \ 
        -Dconvertigo.engine.billing.persistence.jdbc.username=[username for the c8oAnalytics db] \
        -Dconvertigo.engine.billing.persistence.jdbc.password=[password for specified db user]   \
        -Dconvertigo.engine.billing.persistence.jdbc.url=jdbc:mysql://mysql:3306/c8oAnalytics"   \

Convertigo workspace

Projects are deployed in the Convertigo workspace, a simple file system directory. You can map the docker container /workspace to your physical system by using :

$ docker run --name C8O -v $(pwd):/workspace -d -p 28080:28080 convertigo

You can share the same workspace by all Convertigo containers. In this case, when you deploy a project on a Convertigo container, it will be seen by others. This is the best way to build multi-instance load balanced Convertigo server farms.

Migrate from an earlier version of Convertigo

  • Stop the container to perform a backup. And just back the workspace directory. This will backup all the projects definitions and some project data.
  • Start a new Convertigo docker container mapping the workspace
  • All the workspace (projects) will be automatically migrated to the new Convertigo version


The default administration account of a Convertigo server is admin / admin and the test platform is anonymous.

These accounts can be configured through the administration console and saved in the workspace or with CONVERTIGO_ADMIN_USER and CONVERTIGO_ADMIN_PASSWORD variables.

You can change the default administration account :

$ docker run -d --name C8O -e CONVERTIGO_ADMIN_USER=administrator -e CONVERTIGO_ADMIN_PASSWORD=s3cret -p 28080:28080 convertigo

You can lock the test platform by setting the account :

$ docker run -d --name C8O -e CONVERTIGO_TESTPLATFORM_USER=tp_user -e CONVERTIGO_TESTPLATFORM_PASSWORD=s3cret -p 28080:28080 convertigo

Environment variables

Convertigo is based on a Java process with some defaults JVM options. You can override our defaults JVM options with you own.

Table 3 - 2: Environment variables

Environment variable Description
JAVA_OPTS Add any Java JVM options such as -D[something] :

$ docker run -d –name C8O -e JAVA_OPTS=”-DjvmRoute=server1” -p 28080:28080 convertigo
All the configuration parameters in the Convertigo administration console can be set when running docker.
Find complete list of Convertigo Java System Properties on this link.
JXMX Convertigo tries to allocate this amount of memory in the container and will automatically reduce it until the value is compatible for the Docker memory constraints. Once the best value found, it is used as -Xmx={JXMX}m parameter for the JVM.
The default JXMX value is 2048 and can be defined :

$ docker run -d –name C8O -e JXMX=”4096” -p 28080:28080 convertigo
COOKIE_PATH Convertigo generates a JSESSIONID to maintain the user session and stores in a cookie. The cookie is set for the server path / by default. In case of a front server with multiple services for different paths, you can set a path restriction for the cookie with the JSESSIONID. Just define the COOKIE_PATH environment variable with a compatible path.
The default COOKIE_PATH value is / and can be defined this way:

$ docker run -d –name C8O -e COOKIE_PATH=”/convertigo” -p 28080:28080 convertigo
COOKIE_SAMESITE Allow to configure the SameSite parameter for generated cookies. Can be empty, “none”, “lax” or “strict”.
The default COOKIE_SAMESITE value is empty and can be defined this way:

$ docker run -d –name C8O -e COOKIE_SAMESITE=lax -p 28080:28080 convertigo

Pre configurated Docker compose stack

You can use this stack to run a complete Convertigo server with FullSync repository and MySQL analytics in a few command lines:

$ mkdir c8oMBaaS<br>
$ cd c8oMBaaS<br>
$ wget
$ docker-compose up -d

Use Convertigo with kubernetes

Kubernetes objects are represented in the Kubernetes API, and can be used with file in .yaml format. For a Kubernetes deployment, we need to create a deployment.yaml file which include all information about the application.

Here is an example of Convertigo deployment file on AKS (Azure Kubernetes Service):

apiVersion: apps/v1beta1
kind: StatefulSet
 name: convertigo-site
 serviceName: c8o-front-site
 replicas: 1
   type: RollingUpdate
       app: convertigo-site
       version: '1.0'
       hash: '123654988765'
     - name: convertigo-container-site
       image: convertigo/convertigo:latest-aks
       imagePullPolicy: Always
       - mountPath: "/workspace"
         name: c8o-workspace-volume-site
       - containerPort: 28080
       - name: MY_POD_NAME
       - name: JAVA_OPTS
         value: "
     - name: c8o-workspace-volume-site
         claimName: c8o-volume-claim-site
apiVersion: v1
kind: Service
 name: c8o-front-site
 externalTrafficPolicy: Local
 type: NodePort
 - port: 80
   targetPort: 28080
   app: convertigo-site

apiVersion: v1
kind: PersistentVolumeClaim
 name: c8o-volume-claim-site
   - ReadWriteMany
 storageClassName: c8o-volume-storage-class
     storage: 1Gi