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 especially 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 Lenses.io Lenses Service
After=nginx.service
Requires=zookeeper.service

Proxy or Ingress

It is often required to setup Lenses behind a proxy server, load balancer, ingress or another type of middleware. The only care required, is to allow WebSocket connections as the software needs them to function correctly.

These two paths are used for WebSocket connections:

  • /api/ws
  • /api/kafka/ws

Sample Apache configuration

# Add these settings to your httpd.conf or under the VirtualHost section
# for Lenses.
# The rewrite directives need the rewrite module:
#   LoadModule rewrite_module modules/mod_rewrite.so
# The proxy directives need the proxy, proxy_http and proxy_wstunnel modules:
#   LoadModule proxy_module modules/mod_proxy.so
#   LoadModule proxy_http_module modules/mod_proxy_http.so
#   LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule ^/(.*)$           ws://lenses.url:9991/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
RewriteRule ^/(.*)$           http://lenses.url:9991/$1 [P,L]

ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://lenses.url:9991/
ProxyPassReverse / http://lenses.url:9991/

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

Sample NGINX configuration

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;
    }
}

TLS Termination

Lenses supports TLS termination out of the box (see Enabling TLS) but it is also common and well supported to setup a proxy server (such as Apache, Nginx, and Caddy) in front in order to be able to further tweak the TLS configuration, use existing infrastructure for TLS certificate management and more. Please do not forget to allow WebSocket connections through the proxy.