Knowage Business Intelligence on AWS User Guide

Overview

This image runs Knowage, the open source business intelligence and analytics suite from the KnowageLabs project (Engineering Group). Knowage lets teams build interactive dashboards (called cockpits), pixel perfect reports, self service data exploration, charts and KPI monitoring over their own data, and federate multiple data sources into a single analytical model. A complete analytics platform is running within minutes of launch, with full ownership of your data.

Knowage runs as a Java web application on Apache Tomcat 9 with the OpenJDK 17 runtime, bound to loopback 127.0.0.1:8080, behind nginx acting as a TLS reverse proxy on port 443 with a per instance self signed certificate; port 80 redirects to 443. A PostgreSQL 17 metadata database, listening on loopback only and stored on a dedicated data volume, holds the users, roles, data source definitions, datasets and analytical documents. A second dedicated volume holds the Tomcat application tier. Systemd manages the Tomcat service, PostgreSQL and nginx, starting them on boot and restarting them on failure. The Vue based web interface is served under /knowage-vue/, so the bare root redirects there.

Knowage ships several well known default accounts (biadmin, biuser, bidemo, bitest, bidev). On the first boot of every deployed instance a one shot service generates fresh per instance encryption secrets, a fresh PostgreSQL role password and a fresh administrator password, rotates the biadmin account to that per instance password, and removes every other seeded default account, all before the public web interface is started. Two instances launched from the same Amazon Machine Image therefore never share credentials, and none of the well known default logins work on a deployed instance. The administrator password is written to /root/knowage-credentials.txt with mode 0600 so that only the root user can read it.

This image ships the GNU AGPL-3.0 open source Knowage Community distribution unmodified.

Prerequisites

• An AWS account subscribed to the Knowage listing on AWS Marketplace.
• A key pair in your target region for SSH access.
• A security group allowing inbound TCP 443 (HTTPS) from the networks that need the web interface, and TCP 22 (SSH) from your administrative network. Port 80 is only used to redirect visitors to HTTPS.
• The recommended instance type is m5.large (2 vCPU, 8 GiB) or larger. Knowage is a JVM and Tomcat application alongside PostgreSQL and benefits from memory.

Connecting to your instance

SSH in as the default login user for your operating system variant, using your key pair.

ssh -i /path/to/key.pem ubuntu@<instance-public-ip>

Retrieve the administrator password

The per instance administrator credentials are written on first boot to a root only file. Read them with sudo:

sudo cat /root/knowage-credentials.txt

This prints the sign in URL, the administrator login (biadmin) and the generated administrator password, plus the metadata database credentials. These values are unique to this instance.

Confirm the services are running

Knowage runs as three systemd units: the Tomcat application server, PostgreSQL and nginx.

systemctl is-active knowage-tomcat postgresql nginx

Each line should read active.

Confirm the web interface answers over TLS

nginx serves the Knowage web interface on port 443 with a per instance self signed certificate. From the instance you can confirm it answers (the -k flag accepts the self signed certificate):

curl -sk -o /dev/null -w 'knowage-vue HTTP %{http_code}\n' https://127.0.0.1/knowage-vue/

This should print knowage-vue HTTP 200.

Verify the credential rotation

The image ships a helper that proves the per instance administrator password authenticates through the real Knowage login, while the shipped default biadmin/biadmin and any wrong password are rejected:

sudo /usr/local/sbin/knowage-roundtrip.sh

A successful run prints a line beginning OK knowage-roundtrip.

Sign in to Knowage

Open https://<instance-public-ip>/ in your browser. Because the TLS certificate is a per instance self signed certificate, your browser will show a certificate warning the first time; accept it to proceed, or install a certificate for your own domain as described below. Sign in with the login biadmin and the password from /root/knowage-credentials.txt.

The workspace

The workspace is your personal area for building analytics. From here you reach your data (datasets), your models and your analyses, and you create new cockpits and reports over them. Use the left hand categories to switch between Recent items, My Repository, My Data, My Models and My Analysis.

The document browser

The document browser organises the analytical documents published on the server, such as cockpits, reports and dashboards, into folders you can browse, search and share with other users and roles.

Building your first analysis

1. As biadmin, open the administration area and define a data source pointing at the database you want to analyse (Knowage ships the PostgreSQL, MySQL, MariaDB and Oracle JDBC drivers).
2. Create a dataset over that data source with a SQL query or by selecting tables.
3. Create a cockpit and add widgets (tables, charts, selectors) bound to your dataset to build an interactive dashboard.
4. Save the cockpit and share it with the users and roles who should see it.

The metadata database on this instance stores every data source, dataset and cockpit you create; your analysed data stays in whatever external database you connect to.

Architecture and security

• Loopback only application and database. Tomcat listens on 127.0.0.1:8080 and PostgreSQL on 127.0.0.1:5432. Neither is reachable from outside the instance. nginx on port 443 is the only public surface.
• TLS by default. nginx terminates TLS with a per instance self signed certificate; port 80 redirects to 443.
• Per instance credentials. First boot generates fresh encryption secrets, a fresh database password and a fresh administrator password, rotates biadmin and removes every other seeded default account before nginx starts.
• Dedicated data volumes. The PostgreSQL metadata database lives on its own EBS volume at /var/lib/postgresql, and the Tomcat application tier on a second volume at /opt/knowage-tomcat, each independently resizable.

Using your own domain and a CA signed certificate

To serve Knowage under your own hostname with a trusted certificate, point a DNS record at the instance, then replace the self signed certificate that nginx uses at /etc/nginx/tls/knowage.crt and /etc/nginx/tls/knowage.key with a certificate for your domain (for example one obtained with certbot), and reload nginx:

sudo nginx -t && sudo systemctl reload nginx

Backups

Back up the PostgreSQL metadata database regularly with pg_dump as the postgres user, and snapshot the /var/lib/postgresql volume. The metadata database holds all of your data source definitions, datasets, cockpits and reports.

Support

This image is published and maintained by cloudimg with 24/7 support. For deployment help, data source configuration, cockpit and report design, TLS setup or scaling, contact support@cloudimg.co.uk.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.