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/
└── logs/

Before starting Lenses you will need to configure lenses.conf. Follow the configuration instructions at the Configuration section.

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

The bin folder contains the start scripts. 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 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:

Install under /opt
Make sure the directory is owned by the root user
Create a user specially for Lenses
The configuration file may be placed under /opt/lenses/lenses.conf, /etc/lenses/lenses.conf or passed in at the command line when staring Lenses.
```
bin/lenses myconf.conf
```
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
```
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 is on a current Linux distribution and it uses the systemd service manager, the script below can be used to start and stop Lenses with the management and supervision facilities of systemd.

[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

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