LUM - Installation Guide

Overview

License Usage Manager (LUM) is a standalone micro-service (lum-server) with its own database (lum-database).


Both lum-server and lum-database are dockerized and should be deployed as docker containers.

docker images are stored in nexus repo at acumos.org

lum-server container

  • exposes port 2080 for json based communication over http
  • provides swagger-ui at the path of /ui/openapi. See LUM - Application Programming Interface (API)
  • can be preconfigured at startup to connect to the non-default lum-database container through providing etc/config.json mounted as volume and/or by providing environment variables like $DATABASE_PASSWORD
  • is expected to be hidden behind the firewall and should not be exposed to a non-authorized access

lum-database container

  • is a Postgres database with the schema dedicated to LUM
  • exposes the standard Postgres port 5432
  • expects the internal folder /var/lib/postgresql/data to be mounted to a dedicated docker volume for persisting of the database data
  • is expected to be hidden behind the firewall and should not be exposed to a non-authorized access

Note

Any technology that is based on docker can be used to deploy the LUM services.

In this guide the instructions for docker-compose are provided.


Prerequisites

Hardware and Software Requirements

  • Either one or two Linux based virtual machine(s) with running docker-engine
  • Ideally, the lum-database should be installed on a dedicated vm with dedicated reliable and high-performance docker volume for data storage

Preparing for Installation

Populate the docker-compose.yml

  1. pick the latest or specific version for LUM

    services:
      lum-database:
        image: nexus3.acumos.org:10004/acumos/lum-db:1.3.1
      lum-server:
        image: nexus3.acumos.org:10004/acumos/lum-server:1.3.1
        depends_on:
          - lum-database
    
  2. decide on and map the external port to the exposed port 2080 on lum-server

    • for these instructions let’s assume lum-server maps to external port 8600
    lum-server:
      ...
      ports:
        - "8600:2080"
    
  3. mount the volumes

    • letting lum-database to persist its database data to the precreated docker volume lum-data-volume on the hosting virtual machine

    • letting lum-server to write the log file log-acu/lum-server/lum-server.log into precreated docker volume cognita-logs for ELK on Acumos platform

      services:
        lum-database:
          ...
          volumes:
            - lum-data-volume:/var/lib/postgresql/data
      
        lum-server:
          ...
          volumes:
            - cognita-logs:/opt/app/lum/log-acu
      
      volumes:
        lum-data-volume:
          external: true
        cognita-logs:
          external: true
      
  4. configure lum-server clients to find it at the selected port 8600

    • assuming lum-server runs at that external port 8600
    • assuming acumos-portal-be finds lum-server through the docker-compose network
    acumos-portal-be:
      environment:
        SPRING_APPLICATION_JSON: '{
            ...
            "lum": {"url" : "http://lum-server:8600"},
            ...
          }'
    

The resulting subset of docker-compose.yml that is related to LUM

version: "3.4"
services:
  lum-database:
    image: nexus3.acumos.org:10004/acumos/lum-db:1.3.1
    ports:
      - "5432:5432"
    volumes:
      - lum-data-volume:/var/lib/postgresql/data
    restart: always

  lum-server:
    image: nexus3.acumos.org:10004/acumos/lum-server:1.3.1
    depends_on:
      - lum-database
    ports:
      - "8600:2080"
    volumes:
      - cognita-logs:/opt/app/lum/log-acu
    restart: always

  acumos-portal-be:
    environment:
      SPRING_APPLICATION_JSON: '{
          ...
          "lum": {"url" : "http://lum-server:8600"},
          ...
        }'

volumes:
  lum-data-volume:
    external: true
  cognita-logs:
    external: true

Additional configuration options

Advanced configuration of lum-database

It is possibe to change the configuration of lum-database by providing specific Postgres environment variables in docker-compose.yml. For instance,

services:
  lum-database:
    ...
    environment:
      POSTGRES_USER: ${LUM_POSTGRES_USER}
      POSTGRES_PASSWORD: ${LUM_POSTGRES_PASSWORD}

Configuring the lum-server by etc/config.json file

lum-server reads the /opt/app/lum/etc/config.json file at startup as the source for the initial configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "lumServer": {
        "database": {
            "user": "lumdb",
            "password": "lumdb",
            "host": "lum-database",
            "database": "lumdb",
            "port": 5432,
            "max": 100,
            "idleTimeoutMillis": 30000
        },
        "serverName": "lum-server",
        "maxTxRetryCount": 10,
        "logging": {
            "logLevel": "info",
            "logTo": {
                "console": true,
                "devLog": false,
                "healthcheck": false,
                "acumos": true
            }
        }
    }
}
Field definition for etc/config.json file
field required description
{"lumServer": {}}
required top level
{"lumServer": {
  "database": {}}}
required configuration of the database client
{"lumServer": {"database": {
  "user": "lumdb"}}}
required database user must be lumdb to match the owner of the schema in lum-database
{"lumServer": {"database": {
  "password": "lumdb"}}}
optional database user password. When not provided, must be overriden by the environment variable DATABASE_PASSWORD
{"lumServer": {"database": {
  "host": "lum-database"}}}
required hostname of the database
{"lumServer": {"database": {
  "port": 5432}}}
required port of the database
{"lumServer": {"database": {
  "max": 100}}}
optional maximum number of clients the pool of connections to the database should contain. By default this is set to 10
{"lumServer": {"database": {
  "idleTimeoutMillis": 30000}}}
optional number of milliseconds a client must sit idle in the pool and not be checked out before it is disconnected from the backend and discarded. Default is 10000 (10 seconds) - set to 0 to disable auto-disconnection of idle clients
{"lumServer": {
  "serverName": "lum-server"}}
optional the name of the lum-server to be used in logging and healthcheck. Defaults to lum-server
{"lumServer": {
  "maxTxRetryCount": 10}}
optional number of times the lum-server will retry to connect to the database or retry the dead-locked transaction. Defaults to 20
{"lumServer": {
  "logging": {}}}
optional configure logging
{"lumServer": {"logging": {
  "logLevel": "debug"}}}
optional log level in LUM server. enum: (error, warn, info, debug). Defaults to “info”
{"lumServer": {"logging": {
  "logTo": {}}}}
optional collection of loggers to turn off or on in LUM server
{"lumServer":
  {"logging": {"logTo": {
    "console": true}}}}
optional logging the dev info to console. Defaults to true
{"lumServer":
  {"logging": {"logTo": {
    "devLog": true}}}}
optional whether to log the dev info into file logs/dev_lum-server.log in LUM’s internal format. Defaults to false. When a non empty environment variable $LOGDIR is provided, defaults to true.
{"lumServer":
  {"logging": {"logTo": {
    "healthcheck": true}}}}
optional whether to log healthcheck into file logs/healthcheck_lum-server.log. Defaults to false. When a non empty environment variable $LOGDIR is provided, defaults to true.
{"lumServer":
  {"logging": {"logTo": {
    "acumos": true}}}}
optional whether to log info in Acumos specific format (json) to file log-acu/lum-server/lum-server.log. Defaults to true.

Overriding the etc/config.json file in lum-server container

When required, the default internal file etc/config.json can be substituted in the lum-server container through the docker volume mounting mechanism.

For instance, the local read-only file ../config/lum-config.json from the hosting virtual machine is used by lum-server instead of the default internal file /opt/app/lum/etc/config.json
services:
  lum-server:
    ...
    volumes:
      ...
      - ../config/lum-config.json:/opt/app/lum/etc/config.json:ro

Changing the lumdb user password in lum-server

In case the password of the schema owner lumdb has changed from the default value, the new value ${LUMDB_PASSWORD} can be provided to lum-server through environment variable DATABASE_PASSWORD. The environment variable DATABASE_PASSWORD will override the value of lumServer.database.password field taken from etc/config.json file.

services:
  lum-server:
    ...
    environment:
      DATABASE_PASSWORD: ${LUMDB_PASSWORD}

Note

currently, the initdb scripts do not provide the automated way to change the password for lumdb user in lum-database


Installation

Use the docker-compose up command from the folder that contains docker-compose.yml

docker-compose up -d

Verifying the Installation

Tip

Assuming that the hostname of the virtual machine is my-acumos-vm.mycompany.com and that the lum-server runs at that external port 8600

get the healthcheck of the lum-server

curl -X GET "http://my-acumos-vm.mycompany.com:8600/"

The sample healthcheck response

{
  "requestId": "10fff4f5-f731-4ccc-8ed7-58397741a418",
  "requested": "2020-04-23T17:23:56.584Z",
  "healthcheck": {
    "serverName": "lum-server",
    "serverVersion": "1.3.3",
    "apiVersion": "1.3.3",
    "nodeVersion": "12.16.1",
    "databaseInfo": {
      "pgVersion": "PostgreSQL 11.5 on x86_64-pc-linux-musl, compiled by gcc (Alpine 8.3.0) 8.3.0, 64-bit",
      "databaseVersion": "0.28.2",
      "schemaCreated": "2020-01-09T17:12:31.791Z",
      "schemaModified": "2020-01-09T17:12:31.791Z",
      "databaseStarted": "2020-03-02T15:27:31.590Z",
      "databaseUptime": "52 days 01:56:24.999634",
      "checked": "2020-04-23T17:23:56.589Z"
    },
    "serverRunInstanceId": "d3c8d742-4402-4384-aebf-d4d04fe1b6bc",
    "serverStarted": "2020-04-21T18:53:14.137Z",
    "serverUptime": "1 day 22:30:42.481911",
    "pathToOpenapiUi": "/ui/openapi"
  }
}

Optional Post Installation Configuration

Tip

Assuming that the hostname of the virtual machine is my-acumos-vm.mycompany.com and that the lum-server runs at that external port 8600

Get current config of the lum-server

curl -X GET "http://my-acumos-vm.mycompany.com:8600/admin/config"

The sample GET /admin/config response

{
  "requestId": "37f61860-be03-4bef-a53d-32f51f82fb29",
  "requested": "2020-04-23T16:36:22.536Z",
  "config": {
    "database": {
      "user": "lumdb",
      "password": "***-sha256(66c199d8a03e95599c1043bc484995d44619be2f2c0d82fe6b3d66fb838533a4)***",
      "host": "lum-database",
      "database": "lumdb",
      "port": 5432,
      "max": 100,
      "idleTimeoutMillis": 30000
    },
    "serverName": "lum-server",
    "maxTxRetryCount": 10,
    "logging": {
      "logLevel": "info",
      "logTo": {
        "console": true,
        "devLog": "/opt/app/lum/logs/dev_lum-server.log",
        "healthcheck": "/opt/app/lum/logs/healthcheck_lum-server.log",
        "acumos": "/opt/app/lum/log-acu/lum-server/lum-server.log"
      }
    },
    "port": 2080
  }
}

Change the log level and log destination on the lum-server

The following request will change the log level to debug and turn off logging of healthcheck

curl -X PUT "http://my-acumos-vm.mycompany.com:8600/admin/config" \
-H  "accept: application/json; charset=utf-8" \
-H  "Content-Type: application/json; charset=utf-8" \
-d "{\"config\":{\"logging\":{\"logLevel\":\"debug\", \
     \"logTo\":{\"healthcheck\":false,\"acumos\":true}}}}"

The sample PUT /admin/config response

{
  "requestId": "5f6efc69-bbad-4418-8ccd-f82501f0b278",
  "requested": "2020-04-23T17:33:23.800Z",
  "config": {
    "database": {
      "user": "lumdb",
      "password": "***-sha256(66c199d8a03e95599c1043bc484995d44619be2f2c0d82fe6b3d66fb838533a4)***",
      "host": "lum-database",
      "database": "lumdb",
      "port": 5432,
      "max": 100,
      "idleTimeoutMillis": 30000
    },
    "serverName": "lum-server",
    "maxTxRetryCount": 10,
    "logging": {
      "logLevel": "debug",
      "logTo": {
        "console": true,
        "devLog": "/opt/app/lum/logs/dev_lum-server.log",
        "healthcheck": false,
        "acumos": "/opt/app/lum/log-acu/lum-server/lum-server.log"
      }
    },
    "port": 2080
  }
}

Upgrading From a Previous Release

Note

The database schema of lum-database was not changed in Demeter release in comparison to Clio release. This might not be the case in the future.


Uninstalling

Use the docker stop or docker-compose down and related commands to stop and remove the containers and images and volumes.

Danger

Only if you do not need the database data anymore - then manually remove the files from precreated volumes like lum-data-volume by OS commands like rm -rf.


back to LUM index