Creating New Client

This document describe technical process of creating new client. For end user documentation, refer to Create New Client in user documentation.

The sequence of actions behind the scene upon creating new client are outlined in this document. Each event that occurs beginning from 01_install_mariadb.yml to 05_install_keycloak.yml represents a structured process for provisioning and configuring a new client in the Trekker infrastructure.

Below is a detailed step-by-step explanation:

1. Create MariaDB Schema

(01_install_mariadb.yml)

Key Actions:

  • Create a database schema for the client
  • Each client will have their own schema as part of multitenancy architecture
  • A variable named client passed at command line will be used as name of the schema.
  • if the same client name is used, this actions will not recreate the schema.
  • access to the newly created schema will be granted to a user named traccar.

Command Line

Executing the command line requires the client parameter. It will be use for constructing name of the database.

ansible-playbook -i inventory 01-install_mariadb.yml --extra-vars '{"client":"demo","device_port": 5777}'

Outcome:

  • A new database schema named traccar_demo will appear in the database
  • A user named traccar will have full access to the new database schema.

2. Deploy CouchDB

(02_install_couchdb.yml)

Key Actions:

  • Deploy CouchDB container for a client.
  • A data directory under /opt/cdbdata/[client] is created for each client
  • Set up databases tables in the new container
  • Headcount snapshots.
  • Manhour snapshots.
  • Other tenant-specific data structures.
  • Deploy a docker.ini configuration file shared by couchdb docker container.

Command Line

Executing the command line requires a client variable

ansible-playbook -i inventory 02-install_couchdb.yml --extra-vars client=demo

Outcome:

3. Deploy Traccar

(03_install_traccar.yml)

Key Actions:

  • Deploy Traccar container to handle GPS data ingestion from client devices.
  • Traccar service requires a specified port to listen to GPS device (e.g., port 5051).

Command Line

Executing the command line requires 2 parameter. client and device_port to be specified. Both parameter must be unique.

ansible-playbook -i inventory 03_install_traccar.yml --extra-vars '{"client":"demo","device_port":5051}'

Outcome:

  • A new Traccar container named traccar_demo installed and configured.
  • GPS data will be collected via port 5051 from gps devices.
  • The traccar instance can be accessed via https://demo.abc.trekker.my

4. Install Automation Script

(install_webui.yml)

Despite its name being remnant of legacy code, this playbook script does not deploy a webui container. It serves to configure automation tasks as describe below.

Key Actions:

  • Create a script directory.
  • Install additional required Python library to support python scripts that will be installed.
  • Install script for generating headcount snapshot.
  • Create Cron scheduler for generating headcount snapshot
  • Install script for auto-correction fix_headcount.py
  • Install Cron scheduler for headcount snapshot auto correction
  • Install Cron scheduler for manhour snapshot auto correction
  • Install georest-cron at Mariadb2 server to pre-cache georest API for the client specified here

Notes: In addition, depending on client project requirements, additional tasks can be executed such as deploying geotracker-manhour, contact-tracing and ccontact for integrated user option. These options are not fully automated and must be manually enabled or disabled in the script as needed.

Command Line:

Executing the command line requires 2 parameter. client and device_port to be specified. Both parameter must be unique.

ansible-playbook -i inventory install_all.yml --extra-vars '{"client":"mrcsb2","device_port": 5093"}'

Outcome:

5. Create Keycloak Realm

(05_install_keycloak.yml)

Key Actions:

  • Set Up a Client Space (Realm)
  • Create an Admin App (called geotracker-admin) that allows authorized users or services to manage data and settings in the system.
  • Create a User Interface App (called geotracker-webui) for the system’s public-facing end users.
  • Define Roles as that determine what actions a logged in user is allowed to perform.
  • Manual Alert for Special Roles: while certain roles (like "trekker-admin") are created, they need to be manually customized in the Keycloak dashboard.
  • Create a Group and Subgroup: A Plant group is created, representing a specific location or team. A subgroup for the client is added under the Plant group to organize users by client-specific needs.
  • Add and assign Admin User

Command Line

Executing the command line requires 2 parameter. client and device_port to be specified. Both parameter must be unique.

ansible-playbook -i inventory 05-install_keycloak.yml --extra-vars '{"client":"demo","device_port": 5189}'

Outcome:

  • Keycloak is created and configured with a new realm for the client.
  • Additional configuration is required to enable Webui dashboard. Refer to Defining SSO Admin Client in user documentation

Executing All With One Command Line

Alternative to creating client component one-by-one as mentioned above. A one command execute all is provided

ansible-playbook -i inventory install_all.yml --extra-vars '{"client":"demo","device_port": 5189, "ansible_become_pass":"***"}'

Final Validation

  • Verify that all components are properly configured and operational.
  • Conduct connectivity tests between:
  • WebUI and databases (MariaDB, CouchDB).
  • Traccar and Georest.
  • Keycloak and WebUI.
  • Validate tenant-specific functionality using client subdomains.

Outcome

By completing these steps, a new client is fully provisioned in the Trekker infrastructure with access to all necessary services, including data storage, GPS tracking, and user management. This structured approach ensures consistency, security, and scalability.