The following is our guide for the on-premises deployment of Knowi. 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.
FAQs
- General Questions
- Account Management
- Memory
- Email and Notifications
- Logs and Monitoring
Below, you'll find a detailed list of all cloud9.properties
settings and their definitions, followed by a comprehensive troubleshooting guide. This FAQ section is designed to address common questions and issues you may encounter during deployment.
The following is our guide for the on-premises deployment of Knowi. Below, you'll find a detailed list of all cloud9.properties settings and their definitions.
Property | Description |
---|---|
serverExternalHost=http://localhost:9090 | Server public host (where Cloud9 webapp can be accessed externally) |
serverInternalHost=http://localhost:9090 | Server internal host (where Cloud9 webapp can be accessed internally) |
apiHost=http://localhost:9090 | API host where Knowi Agent connects to |
#loginHost= | Login URL where you can specify a custom login page. |
timeZone=America/Los_Angeles | Server timezone (Java compatible timezone ID) |
internalDatabaseType=@db-type-name@ | Relational System Database Type: Either MySQL or PostgreSQL |
mongoDefaultHost=@mongo-host@ |
Mongo Configuration: Empty value to disable Mongo. Uncomment this if you don't want to use `java -Dcloud9.mongo.host`
option. If Mongo requires authentication, the value can be in the format of |
hostedAgentId=HostedAgentID | Hosted Connector ID |
#connectorRealtimeEnabled=false | Realtime Connector: Uncomment this if you wish to disable real-time syncing from the agent. |
Property | Description |
---|---|
messageQueueHost=localhost messageQueuePort=5672 |
This part is only required if you have real-time enabled |
#messageQueueUser= #messageQueuePass= #messageQueueSsl= |
Rabbit MQ configuration |
Property | Description |
---|---|
emailEnabled=false | Enable Email |
#smtpHost= #smtpPort= #smtpUser= #smtpPass= |
Email SMTP server configuration |
#smtpTls= | Set this to true to enable TLS |
#smtpSslAuthentication= | Set this to true to enable SSL Authentication |
#supportEmail= | Support Email Address |
Property | Description |
---|---|
#phantomJsPath=phantomjs | Location for PhantomJS for headless rendering of HTML for PDF exports. Can also be set via the -Dcloud9.phantom.js option or if PhantomJS is already included in your PATH. |
#phantomCachePath= | Location for PhantomJS cache |
#pdfExportPath=/tmp | Location to save exported PDF files |
#pdfExportThreads= | Number of PDF Export threads (default 1) |
Property | Description |
---|---|
userDefaultPlanId=10 | Default plan ID (10: Unlimited) |
#userDefaultCustomerId= | Default customer ID for new user |
#userDefaultRole= | Default user role name for new user |
#userDefaultGroupId= | Default group ID for new user |
userDataRefresh=60 | Session data refresh time in minutes |
ssoTokenExpiry= | SSO Session Expiry (minutes) |
ssoTokenSingleUse= | Set to true if if you want the token to be single use (default is false) |
#appHeaderPath= | App header customization (can be resource name or file path) |
#appFooterPath= | App footer customization (can be resource name or file path) |
#sslKeyStore= #sslKeyStorePass= |
SSL KeyStore settings. These can also be set via JVM system parameters `javax.net.ssl.keyStore` and `javax.net.ssl.keyStorePassword` which if set will supersede the settings here. |
pwdExpirationDays=90 | Users password expiration days |
#reportEnabled= | Enable/Disable email report (enabled by default) |
#alertEnabled= | Enable/Disable alert (enabled by default) |
Property | Description |
---|---|
#nlpEnabled= | Enable/Disable across dataset NLP (disabled by default) |
#nlpIndexerThreads= | Number of NLP indexing threads |
#elasticUrl= | ElasticSearch URL |
#elasticUsername= | ElasticSearch username |
#elasticPassword= | ElasticSearch password |
#elasticIndexPrefix= | ElasticSearch index prefix to store user NLP data inside ElasticSearch (` |
Property | Description |
---|---|
#slackAppId= #slackClientId= #slackVerificationToken= #slackSigningSecret= #slackOAuthAuthorizeUrl= |
Credentials for slack app integration |
Property | Description |
---|---|
#oauthProviderClientId= | Management API credentials of Knowi OAuth owner for third party integrations |
#oauthProviderClientSecret= | Management API credentials of Knowi OAuth owner for third party integrations |
Property | Description |
---|---|
#privateKeyFile=/usr/local/cloud9/.ssh/id_rsa | Private key for tunneling |
Property | Description |
---|---|
#maxChunkSize= | Maximum size of in-memory data chunk for processing user data (default 200000) |
#maxChunkCount= | Maximum number of chunks allowed for processing data (default unlimited) |
#queryJoinThreads=0 | Join query execution threads. These threads are used to execute each part of a single join query concurrently. Setting this to zero will disable this feature (i.e., the join parts of the query will be fetched and processed one after another by the main query thread). |
#chunkSerializationMode= | Serialization mode for data chunks. Valid values are FST, OOS, and NONE. FST: Fast Serialization (default) OOS: Object Output Serialization (use this if running Java 21) NONE: No serialization |
Property | Description |
---|---|
apiKeyUrlAuthEnabled | This allows turning off URL-based authentication for push API (default is TRUE) |
Property | Description |
---|---|
enhancedSession=TRUE | Enhanced session management enables Knowi's session management when enhancedSession=TRUE. With Knowi's session management enabled, once a session is expired, a ?session expired? modal window will appear. Note: Enhanced session defaults to TRUE; however, turning enhancedSession=FALSE will default back to the existing Tomcat session management. |
Issue: How to connect Docker to a local MongoDB and PostgreSQL?
Solution:
Get your host machine IP:
ifconfig
on your host machine and note the local network IP address.Update Docker Compose:
extra_hosts
block to the web
and agent
sections for both MongoDB and PostgreSQL in your docker-compose.yml
file.extra_hosts:
"mongo:10.0.0.79"
"postgresql:10.0.0.79"
Issue: How to upgrade Knowi Docker deployment?
Solution:
Preparation:
knowi-docker-compose
if it is running.Upgrade Tomcat Web App:
knowi-docker-compose
)ROOT.war
to the backup folder.This file should be under <knowi-docker-compose>/web/webapps/ROOT.war
<knowi-docker-compose>/web/webapps/
.<knowi-docker-compose>/web/webapps/
.knowi-docker-compose
.Update Cloud9 Agent: Since we don't want to change any configuration of your agent, we will just replace the JAR files.
knowi-docker-compose
)<agent_home>/lib
and <agent_home>/config
folders to your backup folder./lib: rm -rf <agent_home>/lib/*.jar
./lib/cp <new_agent_tmp_folder>/lib/*.jar <agent_home>/lib/
.Issue: How to host Knowi behind an Nginx reverse proxy in a Docker build?
Solution:
Example is for
<bundle>/web/webapps/
from ROOT.war
to knowi.war
.<bundle>/web/conf/cloud9/cloud9.properties
to append /knowi
to apiHost
, serverExternalHost
, and serverInternalHost
.<bundle>/agent/config/cloud9.properties
to append /knowi
to apiHost
.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
Issue: How to upgrade a non-Docker Knowi deployment?
Solution:
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 so that we can have a fresh log to debug if there is problem:
- 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
Upgrade MySQL DB Schema We are using liquibase and the schema will be upgraded automatically upon starting the server. For this reason, you should backup the "cloud9" database on MySQL first in case you need to roll back.
- Backup the cloud9
database.
- The schema will be automatically upgraded upon starting the server.
Upgrade Tomcat Web App
- Make sure that your Tomcat is stopped.
- Backup ROOT.war
to the backup folder you created.
- 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.
Update Cloud9 Agent Since we don't want to change any configuration of your agent, we will just be replacing the JAR files.
- Make sure that your Cloud9 Agent is stopped.
- Backup the <agent_home>/lib
and <agent_home>/config
folders to the backup folder you created.
- 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.
What are my deployment options?
Do I need to restart Tomcat after changing cloud9.properties
?
How do I remove the sign-up button?
signupEnabled=false
in cloud9.properties
.How do I get a new c9.license
for my renewal?
How do I replace my old c9.license
file?
c9.license
.How do I migrate user level data from one instance to another within on-premises installation?
How do I unlock an account after too many failed attempts to sign in?
failed_login_attempts
to 0 in the users
table.The Ops Dashboard on my account is empty, how can I view it?
Why is the Cloud9Agent tmp folder taking up so much space?
shutdown.sh
file.How do I resolve an Out of Memory
error: java.lang.OutOfMemoryError: Java heap space
?
-Xmx16384m
).What are the recommended memory and storage settings?
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.
Unable to send emails after entering SMTP credentials in c9.properties
. What should I do?
#Email
in c9.properties
are accurate and that emailEnabled=true
.Telnet is a command-line tool that can help diagnose SMTP connection problems. Open a command prompt or terminal and type: telnet
25 (replace with the actual IP address of the SMTP server). 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?
Where can I locate my log files?
<tomcat_home>/logs
(system events and errors)<agent_home>/logs
(query errors and executions)How do I adjust my log4j2.xml
to direct logs to my own logging platform?
/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?
/lib
folder.