Linux

Download and extract 

tar -xvf lenses.tar.gz -C lenses

This will extract the application in a lenses directory. Make sure the directory is owned by the root user.

Configure Lenses 

Use the 2 sample configuration files, included in the directory, and create the Lenses configuration. The sample files are:

lenses.conf.sample
security.conf.sample

1. Enable any configuration points by removing the # comment prefix.
2. Change the values as you want. Here’s the configuration section.
3. Copy or rename the files to their official names:

lenses.conf
security.conf

After that, the final directory structure should be:

   lenses
   ├── lenses.conf       ← edited and renamed from .sample
   ├── security.conf     ← edited and renamed from .sample
   ├── license.json
   ├── logback.xml
   ├── logback-debug.xml
   ├── bin/
   ├── jre/
   ├── lib/
   ├── licences/
   ├── logs/             ← created when you run Lenses
   ├── plugins/
   ├── storage/          ← created when you run Lenses
   └── ui/

Set configuration file permissions 

security.conf contains sensitive information:

• admin user account and password
• LDAP or SSO connection details.

Make it only readable by the Lenses user:

chmod 0600 /path/to/security.conf
chown [lenses-user]:root /path/to/security.conf

Lenses needs write access in 4-5 places in total:

1. [RUNTIME DIRECTORY]
   When Lenses runs, it will create at least one directory under the directory it is run in:
   1. [RUNTIME DIRECTORY]/logs
      Where logs are stored
   2. [RUNTIME DIRECTORY]/logs/lenses-sql-kstream-state
      Where SQL processors (when In Process mode) store state. To change the location for the processors’ state directory, use lenses.sql.state.dir option.
   3. [RUNTIME DIRECTORY]/storage
      Where the H2 embedded database is stored when PostgreSQL is not set. To change this directory, use the lenses.storage.directory option.
2. /run (Global directory for temporary data at runtime)
   Used for temporary files. If Lenses does not have permissions to use /run, it will fallback to /tmp.
3. /tmp (Global temporary directory)
   Used for temporary files (if access to /run fails), and JNI shared libraries. See here for instructions for JNI.

Start Lenses 

Start Lenses by running:

bin/lenses

or pass the location of the config file:

bin/lenses lenses.conf

If you do not pass the location of the config file, Lenses will look for it inside the current (runtime) directory. If it does not exist, it will try its installation directory.

The default settings mean that you can login on http://localhost:9991 using your authentication provider, or with the admin account that comes by default with the admin:admin credentials. We strongly recommend changing the defaults.

Lenses license and connections to external services can be configured through wizard configuration, which will appear at Lenses start up, or via a Lenses CLI provision subcommand.

To stop Lenses, press CTRL+C.

JNI libraries 

Lenses and Kafka itself use two common Java libraries that take advantage of JNI and are extracted to /tmp.

You must either:

1. Mount /tmp without noexec
2. or set org.xerial.snappy.tempdir and java.io.tmpdir to a different location

LENSES_OPTS="-Dorg.xerial.snappy.tempdir=/path/to/exec/tmp -Djava.io.tmpdir=/path/to/exec/tmp"

SystemD example 

If your server uses systemd as Service Manager, then manage Lenses (start upon system boot, stop, restart) with it. Below you can find a simple unit file that starts Lenses automatically on system boot.

[Unit]
Description=Run Lenses.io service

[Service]
Restart=always
User=[LENSES-USER]
Group=[LENSES-GROUP]
LimitNOFILE=4096
WorkingDirectory=/opt/lenses
#Environment=LENSES_LOG4J_OPTS="-Dlogback.configurationFile=file:/etc/lenses/logback.xml"
ExecStart=/opt/lenses/bin/lenses /etc/lenses/lenses.conf

[Install]
WantedBy=multi-user.target

This step will run Lenses in Wizard mode, so connections will be configured through the UI. In the case it is preferred to run Lenses with automatic configuration, then you’ll need a second service.

Automatic Provisioning 

Before continuing, please read about dynamic configuration and lenses-cli provision.

Now, we can create a second unit file that will provision Lenses given a provision.yaml. Find the systemd unit file and provision.sh script below.

#!/usr/bin/env bash

set -o nounset;

LENSES_PROVISION_YAML=${1:-provision.yaml}
LENSES_ADMIN_USER=${LENSES_ADMIN_USER:-admin}
LENSES_ADMIN_PASS=${LENSES_ADMIN_PASS:-admin}
LENSES_PORT=${LENSES_PORT:-9991}
LENSES_HOST=${LENSES_HOST:-localhost}

echo "Loading configuration from ${LENSES_PROVISION_YAML}"
if [ -f "${LENSES_PROVISION_YAML}" ]; then
     echo "Found '${LENSES_PROVISION_YAML}'. Configuring Lenses with the following settings:"
     cat "${LENSES_PROVISION_YAML}"
else
     echo "${LENSES_PROVISION_YAML} not found.  Lenses will not be provisioned. Stopping process."
     exit 1;
fi

lenses-cli provision --wait-for-lenses --setup-mode \
    --host="${LENSES_HOST}":"${LENSES_PORT}" \
    --user="${LENSES_ADMIN_USER}" \
    --pass="${LENSES_ADMIN_PASS}" \
    "${LENSES_PROVISION_YAML}"

# provision.service
[Unit]
Description=Provision Lenses 5.2
serviceAfter=lenses.service

[Service]
Restart=alwaysWorkingDirectory=/opt/lenses/
ExecStart=/usr/bin/env bash /opt/lenses/bin/provision.sh /etc/lenses/provision.yaml

[Install]
WantedBy=multi-user.target

Global Truststore 

Lenses uses the default truststore (cacerts) of the system’s JRE (Java Runtime) installation. The truststore is used to verify remote servers on TLS connections, such as Kafka Brokers with an SSL protocol, Secure LDAP, JMX over TLS, and more. Whilst for some type of connections (e.g. Kafka Brokers) a separate keystore can be provided at the connection’s configuration, for some other connections (e.g. Secure LDAP and JMX over TLS) we always rely on the system truststore.

It is possible to set a global custom truststore via the LENSES_OPTS environment variable:

export LENSES_OPTS="-Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit"
bin/lenses