Configure the servers

Some properties of the two servers used for the licensing and the administration can be respectively edited through the config_devices.ini and config_admin.ini files mounted in the /app directory of the container.

Configure the devices’ server

The devices’ server is the server request by the devices to renew a license or juste request the server’s time. These requests are respectively done through the /l and /t routes.

This server can be configured through the config_devices.ini file :

[Server]
maximum_content_length = 1024

[Db]
max_mariadb_retries = 3
  • Server :
    • maximum_content_length (int) : the maximum number of bytes that can be received by the server before raising an error.
  • Db :
    • max_mariadb_retries (int) : the maximum number of times an SQL request must be retried in the eventuality of an operational error (ex: deadlock).

All the other types of errors cause an abortion of the operation.

Configure the administration server

The administration server is the server requested by administrators in order to monitor and manage the licensing of their products. It serves different features through different API routes and an administration panel.

This server can be configured through the config_admin.ini file :

[Auth]
max-age = 604800

[Db]
max_mariadb_retries = 3
  • Auth :
    • max-age (int) : the maximum supported age of the authentication tokens before expiration, in seconds. (default: 604800).
  • Db :
    • max_mariadb_retries (int) : the maximum number of times an SQL request must be retried in the eventuality of an operational error (ex: deadlock).

Deploy the servers

The deployment of the licensing architecture is orchestrated by Docker compose thanks to a prebuilt image containing the 2 servers (administration and devices) and a MariaDB image. The choice of the database side is free provided that it is a MariaDB database and that its version is greater than v5.1.

The docker-compose.yml file contains all the informations needed to configure and deploy its elements correctly.

Import the Docker image

The image file can be imported in docker using the command:

$ docker load -i <path to image.tar>

Use the loaded image tag in the next step.

Configure the orchestrator

In this example, the configuration of the orchestrator (Docker compose) is done through the docker-compose.yml file :

services:
  mariadb:
    image: mariadb:11
    container_name: mariadb
    environment:
      MARIADB_ROOT_PASSWORD: toor
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 5s
      interval: 10s
      timeout: 5s
      retries: 3
    volumes:
      - mariadb_data:/var/lib/mysql
    expose:
      - "3306"
    networks:
      - licensing

  licensing_server:
    image: sklicensing:0.0.1
    container_name: licensing_server
    ports:
      - "5001:5001" # devices
      - "5002:5002" # admin
    env_file:
      - .env
    volumes:
      - ./app/config_admin.ini:/app/config_admin.ini
      - ./app/config_devices.ini:/app/config_devices.ini
    depends_on:
      mariadb:
        condition: service_healthy
    networks:
      - licensing

volumes:
  mariadb_data:

networks:
  licensing:

The database configuration is fully customizable given that a MariaDB (>v5.1) image is used. As for the configuration of the licensing servers, it is mostly done through these principal sections :

  • ports : the administration and devices’ servers are respectively exposed on the 5001 and 5002 ports of the container. Any forwarding port can be choosed given that they are different.

  • env_file : the environment file that shall contain the following variables :

    • JWT_SECRET_KEY: the secret token used to sign JWTs for authentication purposes. This token should be random bytes encoded in hexadecimal and be at least 32 characters long.
    • DATABASE_HOST: the database host (as configured in the mariadb instance).
    • DATABASE_PORT: the port the database is listening on (as configured in the mariadb instance).
    • DATABASE_ROOT_PASSWORD: the database root user password (as configured in the mariadb instance).
    • DATABASE_DEVICES_USERNAME: the database devices username (will be created if does not exists).
    • DATABASE_DEVICES_PASSWORD: the database devices user password (will be created if does not exists).
    • DATABASE_ADMIN_USERNAME: the database administration username (will be created if does not exists).
    • DATABASE_ADMIN_PASSWORD: the database administration user password (will be created if does not exists).
    • DATABASE_NAME: the database name (will be created if does not exists).

The .env file must be in the following format (the order of the rows doesn’t matter) :

JWT_SECRET_KEY=
DATABASE_HOST=mariadb
DATABASE_PORT=3306
DATABASE_ROOT_PASSWORD=
DATABASE_DEVICES_USERNAME=
DATABASE_DEVICES_PASSWORD=
DATABASE_ADMIN_USERNAME=
DATABASE_ADMIN_PASSWORD=
DATABASE_NAME=licensing

The informations provided for the image must be consistent with the database configuration.

DATABASE_ROOT_PASSWORD, DATABASE_DEVICES_PASSWORD, DATABASE_ADMIN_PASSWORD : these parameters must comply with basic security rules in terms of length (> 11) and charset (alphanumeric and specials characters).

The .env file must be kept strictly confidential and protected from unauthorized access as it contains the token used to sign JWTs.

Special characters shouldn’t be used for the JWT_SECRET_KEY variable to avoid encoding errors.

Manage the orchestrator

In order to deploy the project, it is necessary to start Docker compose :

$ docker compose up

The database will be launched first, then the servers (devices and administration) will start thanks to a periodic healthcheck allowing them to start as soon as the database is fully operational.

The first launch may take longer, as a custom script will initialize the database.

To shut the service down, use :

$ docker compose down

If needed, the database can be deleted with the following command :

$ docker volume rm license-server_mariadb_data

This operation is permanent.

The volume’s name might change depending on the used database management system. If it does, look for it using the docker volume ls command.

Access the administration interface

To access the administration interface, use a browser to connect to the licensing server host using the port mapped to the docker container 5002 port. You should see a login page. The default credentials are:

Username:

admin

Password:

changeme

Once logged in, the password can be changed from the Settings page.