Deploying HQ

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

To install the HQ from the archive you must:

1. Extract the archive

2. Configure the HQ

3. Start the HQ

---

Extracting the archive

Extract the archive using the following command

terminal

tar -xvf hq-v6.tar.gz -C lenses-hq

Inside the extract archive, you will find.

terminal

   lenses-hq
   ├── backend-darwin-arm64

---

Configuring the HQ

In order to properly configure HQ, two core components are necessary:

• Postgres database

1

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.

config.yaml

auth:
  users:
    - username: admin
      password: $2a$10$F66cb6ZhnJjGCZuxlvKP1e84eytTpT1MDJcpBblHaZgsqp1/Aa0LG # bcrypt("correcthorsebatterystaple").
  administrators:
    - admin
    - [e-mail]
  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

2

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: true
  tls:
    enabled: true
    cert: ""
    key: ""

More about setting up TLS can be read here.

3

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: ""
    key: ""

More about setting up TLS can be read here.

4

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
  params:
    sslmode: require

5

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
    - [e-mail]
  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
  params:
    sslmode: require
licence:
  key: license_key_*
logger:
  mode: text
  level: debug

---

Starting the HQ

Start Lenses by running:

terminal

./backend-darwin-amd64

or pass the location of the config file:

terminal

./backend-darwin-amd64 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 the Agent (start upon system boot, stop, restart). Below is a simple unit file that starts the Agent automatically on system boot.

[Unit]
Description=Run Lenses.io service

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

[Install]
WantedBy=multi-user.target