Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt

Use this file to discover all available pages before exploring further.

Kameleoon typically uses a Software as a Service (SaaS) model. In this model, Kameleoon hosts customer data (such as experiments, personalizations, and accounts) on a common platform. Kameleoon uses approximately 150 physical servers (as of 2023) to support functional features, including script hosting, data collection, storage, and analytical reports. Kameleoon shares data on common servers for all customers and maintains logical separation between customer data. The application code implements restrictions to prevent customers from accessing other customers’ data. Kameleoon groups customers into clusters based on their geographic location (country). For example, French customers share data within the French data cluster, while German customers share data within the German clusters. Kameleoon always physically hosts a country’s cluster in a data center on that country’s soil to ensure data confidentiality and compliance with regional data privacy laws. Even in the default SaaS model, Kameleoon hosts the data collected on your website in your country and follows local laws. Customers usually choose self-hosting or on-premises mode for performance, data confidentiality, or security reasons. Kameleoon fully supports the on-premises model and offers three options for self-hosting. The first option allows you to host the critical Kameleoon application file (and optionally, public resources such as images) on your own servers or CDN. This option requires 2-3 days to set up. The second option requires setting up a dedicated data storage cluster and takes 1-2 weeks. The third option provides a full on-premises configuration where you host absolutely everything on dedicated servers. This setup typically takes 1-2 months.

​
Application file & public resources self-hosting

The simplest on-premises option allows you to self-host the application file. You can safely host the Kameleoon application file on the Kameleoon CDN (default, SaaS setup) or on your own servers or CDN. Set the configuration option in the Kameleoon back-office in the website setup section. You can choose from three values: no self-hosting, self-host only the application file, self-host only public resources, or full self-hosting (both application file and images). Review the guides for self-hosting with Cloudflare CDN or Fastly CDN.
In addition to choosing the correct self-hosting option, provide the planned hosting URL in the text field. Kameleoon uses this URL to generate a correct installation script and to self-host images (see details below).

​
Application file self-hosting

Hosting the Kameleoon application file on your own servers can provide a small performance boost by removing the additional DNS query and SSL handshake required by the Kameleoon CDN. You may also choose to self-host for security reasons. If you serve the application file from your own servers, you can ensure compliance with internal security policies and manage the security of the hosting servers directly. To self-host the Kameleoon application file, follow these two steps:
  1. Provide the hosting URL for the application file in the installation tag. This results in a slightly modified installation tag compared to the default tags.
For example, if you use the Asynchronous Loading with Anti-Flicker method, the Kameleoon application file defaults to //SITE_CODE.kameleoon.io/engine.js. Change this URL in the installation tag to your own URL (e.g., https://www.customerdomain.com/resources/scripts/engine.js).
  1. Implement synchronization between the file on your servers or CDN and the original file that the Kameleoon platform generates. This step is mandatory because the application file is dynamic; its contents change every time an experiment or personalization status changes on the platform or when you modify the configuration.
The appropriate synchronization method depends on your setup. CDNs provide their own interfaces for this configuration. For standard web hosting on HTTP servers like nginx or Apache, use a simple cron job to run a wget command that retrieves the file. Run this job every 5 minutes. Once you complete these steps, you can use the Kameleoon platform with a self-hosted application file.
You can obtain a hash of the original file’s contents via the Automation API. Use this to verify that the copied file matches the original or to trigger synchronization only when contents change.
The following example provides a ready-to-use installation tag and synchronization commands.

​
Example: Instructions for self-hosting of the Kameleoon application file

<script type="text/javascript">
  // Duration in milliseconds to wait while the Kameleoon application file is loaded
  var kameleoonLoadingTimeout = 750;

  var kameleoonQueue = kameleoonQueue || [];
  var kameleoonStartLoadTime = Date.now();
  if (! document.getElementById("kameleoonLoadingStyleSheet") && ! window.kameleoonDisplayPageTimeOut)
  {
    var kameleoonS = document.getElementsByTagName("script")[0];
    var kameleoonCc = "html::after { content: ''; position: fixed; inset: 0; background: #fff; z-index: 2147483647; }";
    var kameleoonStn = document.createElement("style");
    kameleoonStn.type = "text/css";
    kameleoonStn.id = "kameleoonLoadingStyleSheet";
    if (kameleoonStn.styleSheet)
    {
      kameleoonStn.styleSheet.cssText = kameleoonCc;
    }
    else
    {
      kameleoonS.appendChild(document.createTextNode(kameleoonCc));
    }
    kameleoonS.parentNode.insertBefore(kameleoonStn, kameleoonS);
    window.kameleoonDisplayPage = function(fromEngine)
    {
      if (!fromEngine)
      {
        window.kameleoonTimeout = true;
      }
      if (kameleoonStn.parentNode)
      {
        kameleoonStn.parentNode.removeChild(kameleoonStn);
      }
    };
    window.kameleoonDisplayPageTimeOut = window.setTimeout(window.kameleoonDisplayPage, kameleoonLoadingTimeout);
  }
</script>
<script type="text/javascript" src="//www.customerdomain.com/resources/scripts/engine.js" async="true"></script>
In the snippet above, the script source uses the customer’s URL: //www.customerdomain.com/resources/scripts/engine.js. Below are examples of synchronization commands. 
# wget command

wget https://SITE_CODE.kameleoon.io/engine.js -O /var/www/html/resources/scripts/engine.js -T 30 -t 3

# cron entry

*/5 * * * * wget https://SITE_CODE.kameleoon.io/engine.js -O /var/www/html/resources/scripts/engine.js -T 30 -t 3
Kameleoon script domains vary by project. Projects use either kameleoon.eu or kameleoon.io based on their creation date. Use the domain displayed in the Kameleoon App for your project.
If you use unified session data across subdomains, you must also self-host an additional static iFrame (https://www.customerdomain.com/path/to/kameleoon-iframe.html). Review the Unify session data across subdomains documentation for details.

​
Images self-hosting

You can also self-host images uploaded via the Kameleoon platform. If you choose this option and provide an image URL, the generated URLs for uploaded images use your server or CDN. The standard URL path for uploaded images is SITE_CODE.kameleoon.io/images/. Kameleoon’s CDN serves these resources. If you specify a different path, such as https://server.mydomain.com/path/resources/images/, you must configure your CDN to rewrite /path/resources/images/ to /images/. If you do not require a specific path, use the standard path: https://server.mydomain.com/images/. You must also use a synchronization mechanism for image self-hosting. This process is more complex than synchronizing a single file because you must consider several files and cannot know the exact names and URLs of uploaded images in advance. Use image self-hosting only via a CDN that provides a built-in replication mechanism. Point your CDN to serve resources from the SITE_CODE.kameleoon.io/images/ origin URL.
Kameleoon script domains vary by project. Projects use either kameleoon.eu or kameleoon.io based on their creation date. Use the domain displayed in the Kameleoon App for your project.

​
Dedicated clusters for Data Storage

A separate cluster for data storage physically separates the data collected for visitors on your website from other Kameleoon users. This data resides on dedicated, separate servers and offers the following advantages:
  • Security: Physical separation provides a higher level of security than logical separation.
  • Performance: Dedicated servers ensure optimal speed for storage and operations.
  • Raw-data access: Kameleoon authorizes low-level access to the underlying databases (primarily ClickHouse), allowing your data scientists to run custom queries.
Setting up a dedicated data storage cluster requires installing several open-source database systems. Kameleoon uses four main technologies: Kafka, HDFS, and ClickHouse (mandatory), and Cassandra (depending on your module usage).
  1. Kafka (mandatory): Producers send all data collection events to Kafka topics, making them available to ETL applications.
  2. Hadoop File System (mandatory): Kameleoon stores all data collection events in HDFS. Kameleoon rebuilds visits from this raw data for use in other scalable databases. HDFS serves as the primary datastore and source of truth.
  3. ClickHouse (mandatory): ClickHouse is the OLAP engine Kameleoon uses to create analytical reports. You can run custom queries for advanced analysis.
  4. Cassandra (required for personalization or cross-device reconciliation): Kameleoon uses Cassandra for machine learning models and cross-device history reconciliation.
Experienced Kameleoon engineers usually perform the server setup and configuration. Kameleoon can perform these operations on your data center (servers you own and operate) or on Kameleoon’s data centers.
Review the server requirements for the dedicated data cluster.
Servers must be physical, bare metal servers. Kameleoon does not currently support virtualized servers.
ComponentVersionMinimal serversOptimal serversRecommended RAMStorage typeRemarks
Kafka2.3.12232 GBSpinning disks (8TB+)Confluent v5.3.1
HDFS2.9.12232 GBSpinning disks (8TB+)Requires 2 servers for replication
ClickHouse22.3.31264 GBSSD recommended
Cassandra4.0.11232 GBSSD mandatory
Kameleoon recommends the latest Rocky Linux distribution for all components.
For A/B testing only, use a minimal setup of 5 servers (6 recommended). For personalization, use a minimal setup of 6 servers (8 recommended).

​
Full On-Premises model (separated back-office, data storage cluster, and application file hosting)

In this scenario, you host all Kameleoon platform components and functionality on your IT ecosystem. This allows you to implement custom security policies, such as restricting access to corporate workstations via VPN. The Back-Office application runs on a Tomcat JEE server and uses several standalone Java applications that communicate through ActiveMQ. Kameleoon uses MySQL as a relational database for the back-office and nginx as a high-performance HTTP server to collect data events from browsers. Review the server requirements for the dedicated data pipeline and back-office:
ComponentVersionMinimal serversOptimal serversRecommended RAMStorage typeRemarks
JDK/Tomcat/ActiveMQ1.8/8.0.47/5.14.51132 GBSSD recommendedStandalone Java applications are collocated
MySQL8.0.211132 GBSSD recommended
nginx1.20.11232 GBSpinning disksIncludes proprietary Java log parsing application
Kameleoon recommends the latest Rocky Linux distribution for all components. Kameleoon provides the Back-office application as a WAR file and other modules as JAR files.
You can collocate the MySQL server with the Tomcat JEE server, but Kameleoon recommends avoiding collocation except where noted for security and performance reasons.
For A/B testing, use a minimal setup of 9 servers (11 recommended). For personalization, use a minimal setup of 10 servers (13 recommended). Calculate these numbers by summing the tables and adding one server for application file hosting (subtract one if using a CDN).