Welcome Guest! Log in
Stambia versions 2.x, 3.x, S17, S18, S19 and S20 are reaching End of Support January, 15th, 2024. Please consider upgrading to the supported Semarchy xDI versions. See Global Policy Support and the Semarchy Documentation.

The Stambia User Community is moving to Semarchy! All the applicable resources have already been moved or are currently being moved to their new location. Read more…

Stambia analytics on Docker

    663 stambia plus docker

    Docker is the leading container platform and can be used to run Stambia Analytics inside containers. This article explains how to build a Stambia Analytics container using Tomcat web server. The installation of a docker client and the detailed command options are out of scope of this article, please refer to official documentation at Docker docs

    Prerequisites:

    • stambia analytics zip archive from stambia.org
    • Docker client environment ready

     

    As Stambia Analytics needs to be deployed on a web server, we must use a proper base container such as tomcat:8.5.40. Stambia analytics deployment on JBoss wildfly was also tested (using jboss/wildfly base container), but this article focuses on Tomcat.

    Before building the container we must prepare some configuration files for Tomcat. In the example below I use a tomcat-users.xml file to create a user to connect to Stambia Analytics, a context.xml file to declare an external database, and a context-manager.xml file for security purpose. You should also prepare the necessary jdbc drivers that analytics would need - I use a dedicated "drivers" folder for that.

    Please refer to Stambia Analytics Installation Guide and Tomcat official documentation for more information regarding configurations.

    Once you have gathered all the files, you can prepare a folder to build your container and add the analytics.war extracted from the Stambia Analytics zip archive :

    docker analytics folder

    The wait-for-it script can be used in case you need the container to wait for a particular HOST & TCP port to be reachable from the container before starting up the web server. You can find this script at https://github.com/vishnubob/wait-for-it If you don't need it you can remove the copy line for this file from the Dockerfile

    The Dockerfile looks like this :

    FROM tomcat:8.5.40-jre8-slim
    
    RUN mkdir -p /opt/analytics/jdbc
    
    COPY tomcat-users.xml /usr/local/tomcat/conf/
    
    COPY context.xml /usr/local/tomcat/conf/
    COPY context-manager.xml /usr/local/tomcat/webapps/manager/META-INF/context.xml
    
    COPY ./drivers /usr/local/tomcat/lib
    
    COPY wait-for-it.sh /opt/analytics
    
    ENV STAMBIA_WEBAPP_HOME /opt/analytics
    
    COPY analytics.war /usr/local/tomcat/webapps

    An example can be downloaded here :   document Dockerfile (406 B)  (rename to Dockerfile)

    From this folder type the following commands to build the container image :

    >cd myDockerFolder
    >docker build . -t <containername>

     

    Example :

    >docker build . -t myrepo/analytics

     

    The output should look like this :

    663 docker build output

    Then you can start your container interactively (-it) using the following command :

    >docker run -it -p <hostport>:<guestport> --rm <containername>

     

    By default Tomcat uses port 8080 for http communications, so if you want to expose the internal 8080 port of the Stambia Analytics container to the port 7000 on your host you can run the following command :

    >docker run -it --rm -p 7000:8080 myrepo/analytics

     

    To keep application data accross restarts you can externalize the application folder using the --mount option :

    >docker run -it --rm -p 7000:8080 --mount type=bind,source=D:\Docker\runtime\sharedFolder\analytics,target=/opt/analytics myrepo/analytics

     

    Upgrading an Analytics installation

      After reading this article, please feel free to ask questions on the forum or to the Support Team.

       

      Upgrading from 3.x.x to 3.6.x

      Troubleshooting

      When upgrading to Analytics 3.6, you may have issues with some databases providers.

      Errors such as the following are thrown in console and the datasource is not initialized, so analytics does not work:

      Migration03

      SQL Server

      When this error appears with SQL Server, this may be because of the SQL Server JDBC Driver used is too old.

      Using a more recent JDBC Driver can fix the issue. 

      Sybase ASE

      When this error appears with Sybase ASE, this might be a permission problem on the database.

      Adding 'select into' and 'full logging for alter table' permissions to the Sybase ASE database may fixe the issue.

      This can be done with the following commands:

      sp_dboption 'anaytics_database_name','select into',true
      sp_dboption 'anaytics_database_name','full logging for alter table',true

      Upgrading from 2.x.x to 3.x.x

      Overview of the upgrade process

      Migrating from 2.x.x to 3.x.x requires a particular attention as 3.x.x introduces major improvements and changes.

      A complete migration wizard included in the application has been developed to help users to migrate.

      Please refer to the installation and migration parts of the reference documentation which explain everything.

      We also highly recommend to have a look at the release notes for an overview of what have changed.

       

      Troubleshooting

      Installing Analytics with a MariaDB database might fail on Analytics V3 and MariaDB Version 2.4.0 (or higher).

      This kind of message can be displayed:

      MariaDB01

      To resolve this problem, when you have a MariaDB database as an Analytics database, use the mysql jdbc driver instead of the mariadb jdbc driver.

      As a reminder, the driver is configured in the context.xml file of Tomcat.

       

      Upgrading from 2.x.x to 2.x.x

      Overview of the upgrade process

      • Make a backup of your Analytics WebappHome directory
      • Make a backup of your Analytics installation (or make sure you can reinstall your current version)
      • Please read carefully the Release Notes
      • Download and install the new Analytics version (please ask your Application Server's administrator)
      • Specific operations when upgrading from version 2.0.x to 2.1.x or 2.2.x:
        • Open and Save your analytics repositories in order to migrate them
        • Important note: once opened and saved into Analytics 2.1.x or 2.2.x, a repository can no longer be opened from Analytics 2.0.x.

      Articles

      Suggest a new Article!