Deploying HQ

This page describes the install of the Lenses HQ via an archive on Linux.

To install the HQ from the archive you must:

Extract the archive
Configure the HQ
Start the HQ

Extracting the archive

Installation link

Link to archives can be found here: https://archive.lenses.io/lenses/6.0/hq/ (versioned builds live under the hq/ sub-directory).

Extract the archive using the following command. It unpacks into a lenses-hq/ directory:

terminal

tar -xzf lenses-hq-linux-amd64-latest.tar.gz

Inside the extracted archive, you will find the lenses-hq binary (plus config.yaml.sample, VERSION, licenses):

terminal

   lenses-hq
   ├── lenses-hq          # the binary
   ├── config.yaml.sample
   └── VERSION

Configuring the HQ

In order to properly configure HQ, one core components is necessary as prerequirement:

Postgres database

Configure Authentication

To set up authentication, there are multiple methods available.

You can choose between:

password-based authentication, which requires users to provide a username and password;
and SAML/SSO (Single Sign-On) authentication, which allows users to authenticate through an external identity provider for a seamless and secure login experience.

Both password based and SAML / SSO authentication methods can be used alongside each other.

First to cover is users property.

Users Property: The users property is defined as an array, where each entry includes a username and a password. The passwords are hashed using bcrypt for security purposes, ensuring that they are stored securely.

Second to cover will be administrators. It serves as definition of user emails which will have highest level of permissions upon authentication to HQ.

Assertion Consumer Service endpoint is following

/api/v2/auth/saml/callback?client_name=SAML2Client

config.yaml

auth:
  users:
    - username: admin
      password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG # bcrypt("correcthorsebatterystaple").
  administrators:
    - admin
    - admin@example.com
  saml:
    enabled: true
    metadata: |-
      <?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor>
      ...
      ...
      </md:EntityDescriptor>
    # Defines base URL of HQ for IdP redirects
    baseURL: https://changeme.com # <--- Change this
    # Defines  globally unique identifier for the SAML entity 
    # — either the Service Provider (SP) or Identity Provider (IdP)
    # It's often a URL, but it doesn't necessarily need to resolve to anything
    entityID: https://example.com # <--- Change this
    userCreationMode: sso
    groupMembershipMode: sso

Full auth configuration spec can be found here.

Configure HTTP endpoint

Another part which has to be set in order to successfully run HQ is the http definition. As previously mentioned, this parameter defines everything around HTTP endpoint of the HQ itself and how users will interact with.

Definition of HTTP object is as follows:

config.yaml

http:
  address: :8080
  accessControlAllowOrigin:
    - https://example.com
  accessControlAllowCredentials: false
  secureSessionCookies: false
  tls:
    enabled: true
    cert: |
      -----BEGIN CERTIFICATE-----
      MIIDXTCCAkWgAwIBAgIJALkNfT3d1N8tMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
      BAYTAlVTMRYwFAYDVQQKEw1FeGFtcGxlIENlcnQwHhcNMjUwMzI2MDAwMDAwWhcN
      MzUwMzIzMDAwMDAwWjBFMQswCQYDVQQGEwJVUzEWMBQGA1UEChMNZXhhbXBsZS5j
      b20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5D3jXq5JnE9NnRJ8N
      ...
      -----END CERTIFICATE-----
    key: |
      -----BEGIN PRIVATE KEY-----
      MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...
      ...
      -----END PRIVATE KEY-----

config.yaml

http:
  address: :8080
  accessControlAllowOrigin:
    - https://example.com
  accessControlAllowCredentials: false
  secureSessionCookies: false
  tls:
    enabled: false

More about setting up TLS can be read here. Full http configuration spec can be found here.

secureSessionCookies. With TLS enabled, keep the default (session cookies are flagged Secure). If you access HQ over plain HTTP (for example a remote IP during evaluation), a browser will not send a Secure cookie back, so login appears to loop (repeated 401 on /api/v1/users/me). Set secureSessionCookies: false for HTTP access, or serve HQ behind TLS.

Configure Agent endpoint

After correctly configuring authentication strategy and connection endpoint , agent handling is the last most important box to tick.

The Agent's object is defined as follows:

config.yaml

agents:
  address: :10000
  tls:
    enabled: true
    cert: |
      -----BEGIN CERTIFICATE-----
      MIIDXTCCAkWgAwIBAgIJALkNfT3d1N8tMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
      BAYTAlVTMRYwFAYDVQQKEw1FeGFtcGxlIENlcnQwHhcNMjUwMzI2MDAwMDAwWhcN
      MzUwMzIzMDAwMDAwWjBFMQswCQYDVQQGEwJVUzEWMBQGA1UEChMNZXhhbXBsZS5j
      b20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5D3jXq5JnE9NnRJ8N
      ...
      -----END CERTIFICATE-----
    key: |
      -----BEGIN PRIVATE KEY-----
      MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...
      ...
      -----END PRIVATE KEY-----

config.yaml

agents:
  address: :10000
  tls:
    enabled: false

More about setting up TLS can be read here.

Configure database

Prerequisite:

Running Postgres instance;
Created database for HQ;
Username (and password) which has access to created database;

In order to successfully run HQ, storage within config.yaml has to be defined first.

Definition of storage object is as follows:

config.yaml

database:
  host: postgres:5432
  username: panoptes
  password: password
  database: panoptes
  schema: insert-schema-here
  # Params example - not required and it depends on your PG requirements
  params:
    sslmode: require

params.sslmode: require needs a TLS-enabled Postgres — the connection fails against a server that does not offer TLS. For a local/non-TLS Postgres use sslmode: disable (equivalently set the top-level TLS: false, which maps to sslmode=disable). schema must be an existing schema the role can write to.

Full database configuration spec can be found here.

Configure license and accept EULA

In demo purposes and testing the product you can use our community license

license_key_2SFZ0BesCNu6NFv0-EOSIvY22ChSzNWXa5nSds2l4z3y7aBgRPKCVnaeMlS57hHNVboR2kKaQ8Mtv1LFt0MPBBACGhDT5If8PmTraUM5xXLz4MYv

config.yaml

license:
  key: license_key_*
  acceptEULA: true

Final Configuration File

If you have meticulously followed all the outlined steps, your config.yaml file should mirror the example provided below, fully configured and ready for deployment. This ensures your system is set up correctly with all necessary settings for authentication, database connection, and other configurations optimally defined.

config.yaml

auth:
  users:
    - username: admin
      password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG # bcrypt("correcthorsebatterystaple").
  administrators:
    - admin
    - admin@example.com
  saml:
    enabled: true
    metadata: |-
      <?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor>
      ...
      ...
      </md:EntityDescriptor>
    baseURL: https://example.com
    entityID: https://example.com
    userCreationMode: sso
    groupMembershipMode: sso
http:
  address: ":8080"
  accessControlAllowOrigin:
    - https://example.com
agents:
  address: ":10000"
database:
  host: postgres:5432
  username: panoptes
  password: password
  database: panoptes
  schema: insert-schema-here
  params:
    sslmode: require
license:
  key: license_key_*
  acceptEULA: true
logger:
  mode: text
  level: debug

Starting the HQ

Start Lenses by running:

terminal

./lenses-hq

or pass the location of the config file:

terminal

./lenses-hq config.yaml

If you do not pass the location of the config file, the HQ will look for it inside the current (runtime) directory. If it does not exist, it will try its installation directory.

Once HQ starts, it will be listening on the https://localhost:8080

To stop HQ, press CTRL+C.

SystemD example

If your server uses systemd as a Service Manager, then manage HQ (start upon system boot, stop, restart). Below is a simple unit file that starts HQ automatically on system boot.

The config file (which contains the database password and license) must be readable by the systemd User=. If it is owned by root with mode 0640, HQ fails at startup with Fatal: load config from file: ... permission denied. chown it to the service user.

[Unit]
Description=Run HQ service

[Service]
Restart=always
User=[LENSES-USER]
Group=[LENSES-GROUP]
LimitNOFILE=4096
WorkingDirectory=/opt/lenses-hq
ExecStart=/opt/lenses-hq/lenses-hq /etc/lenses-hq/config.yaml

[Install]
WantedBy=multi-user.target

What's next?

After the successful configuration and installation of HQ, the next steps would be:

PreviousLinux

NextDeploying an Agent

Last updated 18 days ago

Was this helpful?