Manual Deployment

Once you have downloaded the Lenses archive, extract it to a location of your choice. We recommend to avoid white spaces in 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 have not already configured lenses.conf, please do so by following 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 or Ingress

It is often required to setup Lenses behind a proxy server, load balancer, ingress or other type of middleware. Extra care is needed to allow WebSocket connections as the software needs them in order to function correctly.

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

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.