Manual Deployment

Once you have downloaded the Lenses archive, extract it to a location of your choice. We recommend avoiding white spaces for the installation path.

The directory structure is:

lenses
├── LICENSE.txt
├── NOTICE.txt
├── bin/
├── lenses.conf
├── license.json
├── security.json
├── jre8u131/
├── lib/
├── licenses/
├── plugins/
└── logs/

Starting Lenses

If you haven’t already configured lenses.conf, then please follow the configuration instructions at Configuration section.

After the configuration is complete, Lenses is ready to start. You need to deploy one instance of Lenses per Kafka cluster.

Lenses application requires a startup argument which should be the path to the configuration file.

On a Linux server run:

$ bin/lenses

Or to explicitly set the configuration file:

$ bin/lenses lenses.conf

When the application is running, open your browser and navigate to http://address:port based on the configuration file. The default is http://localhost:9991. Log in using the credentials you have provided, otherwise, the default values are admin:admin. We strongly recommend changing the default credentials!

To stop Lenses, press CTRL+C.

Java Options

The following environment variables control the Java configuration (see Java Options) options when starting Lenses:

  • LENSES_HEAP_OPTS - The heap space settings, the default is -Xmx3g -Xms512m
  • LENSES_JMX_OPTS - JMX options so set
  • LENSES_LOG4J_OPTS - Logging options
  • LENSES_PERFORMANCE_OPTS - Any extra options, default is -server -XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:+DisableExplicitGC -Djava.awt.headless=true

Install on server

Some best practice advice can be offered for installation on a server:

  1. Install under /opt

  2. Make sure the directory is owned by the root user

  3. Create a user specially for Lenses

  4. The configuration file may be placed under /opt/lenses/lenses.conf, /etc/lenses.conf, /etc/lenses/lenses.conf or passed in at the command line when staring Lenses.

    bin/lenses myconf.conf

  5. The security configuration file contains information about the users and groups. Please make sure it is only readable by the Lenses user:

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

  6. Please adjust the logs configuration to a path for which the running Lenses process has write access to or, to stdout/stderr in case the log management should happen by the process supervisor. See the logging configuration section for more information.

If your server uses systemd as Service Manager, then you may want to 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 Landoop Lenses 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

If your infrastructure uses additional services managed by Systemd and Lenses depends on them, then you may also want to add one or a combination (based on your setup) of the following options After, Before, wants & Requires into the above service file.

Here is an example that starts lenses after Nginx has started and requires Zookeeper service to be up and running.

[Unit]
Description=Run Landoop Lenses Service
After=nginx.service
Requires=zookeeper.service

Proxy and SSL

Lenses does not support SSL termination but rather relies on a proxy set in front of it (such as Apache, nginx, and Caddy) to provide SSL to clients. Attention should be given to set the proxy to support WebSocket connections under the path /api/kafka/ws.

Sample configuration for Nginx:

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name example.lenses.url;

    # websocket paths
    location /api/ws {
        proxy_pass http://lenses.url:9991;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_redirect off;
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header  Host $http_host;
    }
    location /api/kafka/ws {
        proxy_pass http://lenses.url:9991;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_redirect off;
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header  Host $http_host;
    }

    # all other paths
    location / {
        proxy_pass http://lenses.url:9991;
        proxy_http_version 1.1;

        proxy_redirect off;
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header  Host $http_host;
    }
}

Sample caddy configuration:

proxy /api/kafka/ws http://lenses.url:9991 {
    websocket
}
proxy /api/ws http://lenses.url:9991 {
    websocket
}
proxy / http://lenses.url:9991