What can we help you with?

e.g. Getting Started, Build Dashboards

Top

On-Premises Troubleshooting Guide

Follow

This guide covers key steps for connecting Docker to local databases, upgrading Knowi (Docker and non-Docker), and setting up Knowi behind an Nginx reverse proxy.

General FAQs about the following topics: 

Docker Installations

Connecting Docker to Local Databases

Issue: How to connect Docker to a local MongoDB and PostgreSQL?

Solution:

  1. Get your host machine IP:

    • Run ifconfig on your host machine and note the local network IP address.

  2. Update Docker Compose:

    • Add the extra_hosts block to the web and agent sections for both MongoDB and PostgreSQL in your docker-compose.yml file.

    Example:

    extra_hosts:
    "mongo:10.0.0.79"
    "postgresql:10.0.0.79" 

Upgrading Docker Deployment

Issue: How to upgrade Knowi Docker deployment?

Solution:

  1. Preparation:

    • Create a backup folder on your machine for file backups.
    • Stop knowi-docker-compose if it is running.

  2. Upgrade Tomcat Web App:

    • Ensure Tomcat is stopped. (Stop knowi-docker-compose)
    • Backup your current ROOT.war to the backup folder. This file should be under <knowi-docker-compose>/web/webapps/ROOT.war.
    • Remove all files under <knowi-docker-compose>/web/webapps/.
    • Download and place the new WAR file in <knowi-docker-compose>/web/webapps/.
    • Restart knowi-docker-compose.

  3. Update Cloud9 Agent:

    • Stop the Cloud9 Agent. (Stop knowi-docker-compose)
    • Backup the <agent_home>/lib and <agent_home>/config folders to your backup folder.
    • Remove all JAR files under /lib: rm -rf <agent_home>/lib/*.jar.
    • Download and unzip the new Cloud9 Agent files to a temp folder.
    • Copy new JAR files to /lib: cp <new_agent_tmp_folder>/lib/*.jar <agent_home>/lib/.
    • Restart Cloud9 Agent.

Hosting Knowi Behind Nginx Reverse Proxy

Issue: How to host Knowi behind an Nginx reverse proxy in a Docker build?

Solution:

  1. Example is for /knowi:
    • Rename the WAR file inside <bundle>/web/webapps/ from ROOT.war to knowi.war.
    • Update <bundle>/web/conf/cloud9/cloud9.properties to append /knowi to apiHost, serverExternalHost, and serverInternalHost.
    • Update <bundle>/agent/config/cloud9.properties to append /knowi to apiHost.
    • Update docker-compose.yml to replace: 
      ./web/webapps/ROOT.war:/usr/local/tomcat/webapps/ROOT.war:ro
      with
      ./web/webapps/knowi.war:/usr/local/tomcat/webapps/knowi.war:ro

Non-Docker Installations

Upgrading Non-Docker Deployment

Issue: How to upgrade a non-Docker Knowi deployment?

Solution:

  1. Preparation:

    • Create a backup folder somewhere safe on your machine.
    • Stop both Tomcat Server and Cloud9 Agent (if they are running). The Agent can be stopped by either killing the process or running shutdown.sh script under <agent_home>/ folder.
    • Clean up all the log files: 
      rm -rf <tomcat_home>/logs/*
rm -rf <agent_home>/log/*
    • Download the upgrade bundle and unzip. This zip contains 3 files:
      • c9.license
      • ROOT.war
      • Cloud9AgentLibs.tar.gz

  2. Upgrade MySQL DB Schema:

    • Backup the cloud9 database on MySQL first.
    • The schema will be automatically upgraded upon starting the server.

  3. Upgrade Tomcat Web App:

    • Make sure that your Tomcat is stopped.
    • Backup ROOT.war to the backup folder.
    • Remove all files under <tomcat_home>/webapps/.
    • Copy the new ROOT.war file from the bundle to <tomcat_home>/webapps/.
    • Copy the c9.license file from the bundle to <tomcat_home>/conf/cloud9/.
    • Restart Tomcat.

  4. Update Cloud9 Agent:

    • Stop the Cloud9 Agent.
    • Backup the <agent_home>/lib and <agent_home>/config folders.
    • Remove all JAR files under <agent_home>/lib: rm -rf <agent_home>/lib/*.jar.
    • Copy the new Cloud9AgentLibs.tar.gz from the bundle to a temp folder and unzip.
    • Copy new JAR files to <agent_home>/lib/: cp <new_agent_tmp_folder>/lib/*.jar <agent_home>/lib/.
    • Restart Cloud9 Agent.

 

Frequently Asked Questions (FAQ)

 

General Configuration

What are my deployment options?

  1. Small Deployment: Tomcat + MySQL (Direct queries only)
  2. Medium Deployment: Tomcat + MySQL + Mongo + Agent + RabbitMQ (Direct and scheduled queries)
  3. Full Deployment: Tomcat + MySQL + Mongo + Agent + RabbitMQ + ElasticSearch (Direct and scheduled queries, Natural Language Processing)

Do I need to restart Tomcat after changing cloud9.properties?
Yes, a restart is required for changes to take effect.

How do I remove the sign-up button?
Set signupEnabled=false in cloud9.properties.

How do I get a new c9.license for my renewal?
Ensure your invoice has been paid to Cloud9 Charts, Inc dba Knowi, then request a new license from support@knowi.com.

How do I replace my old c9.license file?

  1. Rename the new license file to c9.license.
  2. Replace the existing c9.license file (found in ../cloud9/c9.license).
  3. Restart your Tomcat server.

How do I migrate user-level data from one instance to another within on-premises installation?
Refer to the following documentation: User Data Migration Script.

 

Account Management

How do I unlock an account after too many failed attempts to sign in?
Reset failed_login_attempts to 0 in the users table.

The Ops Dashboard on my account is empty, how can I view it? 

Ensure that the admin account's 'Datasources' section is correctly configured to point to the appropriate databases.

 

Memory

Why is the Cloud9Agent tmp folder taking up so much space?
The tmp folder stores chunk files when processing large data sets that can't fit in memory. These files are temporary and should be cleaned up upon JVM exit if the agent is properly shut down using the shutdown.sh file.

How do I resolve an Out of Memory error: java.lang.OutOfMemoryError: Java heap space?

Check Tomcat logs for memory limit settings. Ensure the Java memory limit is set to at least 16GB (e.g., -Xmx16384m).

What are the recommended memory and storage settings?

Memory and Storage Recommendations 

 

Test Environment:

  • Knowi Web App: 1 instance, M4 x-large or higher, 4+ CPU, 16GB+ RAM, 50GB SSD.
  • Knowi API Cluster: 1 instance, M4 2x-large or higher, 8+ CPU, 32GB+ RAM, 50GB SSD.
  • MongoDB: 1 stand-alone server, M4 2x-large or higher, 8+ CPU, 32GB+ RAM, 100GB SSD.
  • MySQL: 1 stand-alone server, R4 xLarge or higher, 4+ CPU, 32GB+ RAM, 50GB SSD.
  • Cloud9 Agent: 1 instance, M4 x-large or higher, 8+ CPU, 32GB+ RAM, 50GB SSD.
  • Message Queue: 1 instance, 2+ CPU, 8GB+ RAM, 20GB SSD.
  • ElasticSearch (Optional for NLP): 1 instance, 2+ CPU, 8GB+ RAM, 50GB SSD.

Production Environment:

  • Knowi Web App: 2+ instances, M4 x-large or higher, 4+ CPU, 16GB+ RAM, 50GB SSD per instance.
  • Knowi API Cluster: 2+ instances, M4 2x-large or higher, 8+ CPU, 32GB+ RAM, 50GB SSD per instance.
  • MongoDB: Cluster (refer to MySQL doc), M4 2x-large or higher, 8+ CPU, 32GB+ RAM, 400GB SSD.
  • MySQL: 1+ clusters (refer to MongoDB doc), R4 xLarge or higher, 4+ CPU, 32GB+ RAM, 50GB SSD.
  • Cloud9 Agent: 2+ instances, M4 x-large or higher, 8+ CPU, 32GB+ RAM, 50GB SSD.
  • Load Balancers (UI and API): ELB equivalent, 2+ instances.
  • Message Queue: 2+ instances, R4 large or higher, 2+ CPU, 8GB+ RAM, 50GB SSD.
  • ElasticSearch (Optional for NLP): 1 instance, 2+ CPU, 8GB+ RAM, 50GB SSD.

 

Email and Notifications

I am unable to send emails after entering SMTP credentials in c9.properties. What should I do?

  1. Verify that the credentials under #Email in c9.properties are accurate and that emailEnabled=true.
  2. Test with Telnet:
    • Open a command prompt or terminal and type:
      telnet 25
      (Replace with the actual IP address of the SMTP server and adjust the port number as needed). 25 refers to the port number. If the connection is successful, you should see a response from the server, indicating that you have connected to the SMTP port. If the connection fails or times out, it suggests a connectivity issue.

How do I set up a notification if a query has not been run on the agent?

Set up a data update alert on the dataset you want to monitor.

 

Logs and Monitoring

Where can I locate my log files?

  • Tomcat logs: <tomcat_home>/logs (system events and errors)
  • Agent logs: <agent_home>/logs (query errors and executions)

How do I adjust my log4j2.xml to direct logs to my own logging platform?
Edit /usr/local/webapps/ROOT/WEB-INF/classes/log4j2.xml or replace ROOT with your webapp's name if it has been renamed.

How do I resolve the MYSQL CLIENT_AUTH_PLUGIN Required error?

  1. Check for MySQL version / connector JAR mismatch.
  2. Check for multiple JAR versions in the /lib folder.
  3. Restart Tomcat after making changes.
Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles