Linux archive

Quickstart 

1. 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.

2. 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
   ├── logback.xml
   ├── logback-debug.xml
   ├── bin/
   ├── jre/
   ├── lib/
   ├── licences/
   ├── logs/             ← created when you run Lenses
   ├── plugins/
   ├── storage/          ← created when you run Lenses
   └── ui/

3. Set 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 2 places:

1. lenses/ - when Lenses runs, it will create 2 directories:
   1. lenses/logs - stores 2 kinds of files:
      • log files
      • SQL processors (when In Process mode). To change the location for the processors’ state directory, use lenses.sql.state.dir option.
   2. lenses/storage - Location for Lenses H2 database. To change this directory, use the lenses.storage.directory option.
2. /tmp (Global temporary directory) - Used for temporary files 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

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.

# lenses.service
[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.0
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