Skip to main content

On-premise Deployment

On-premise TIM brings capabilities of TIM to your environment and to your own hardware. On-premise installation of TIM does not require active internet connection and does not send any data outside of the machine. This solution outstands in use-cases with strict security policies and high availability requirements where internet connection may be unstable.

We provide special version of TIM License designed for on-premise usage. Please contact support at support@tangent.works to get more information and request on-premise version of your TIM License.

TIM on-premise solution contains TIM Engine in version v4.4 .

Architecture​

TIM Engine on-premise is by default composed of 10 Docker images:

  • SQL database
    • technology: PostgreSQL 12
    • image: postgres:12
    • containers: 1 container running permanently for entire TIM Engine installation
  • RabbitMQ
    • technology: RabbitMQ 3 with management module
    • image: rabbitmq:3-management
    • containers: 1 container running permanently for entire TIM Engine installation
  • Proxy and webserver
    • technology: Nginx 1.17
    • image: nginx:1.17
    • containers: 1 container running permanently for entire TIM Engine installation
  • Pre-processor
    • technology: Julia
    • image: crwebservices.azurecr.io/tim-webservice:v4.1
    • containers: 1 container running permanently for entire TIM Engine installation
  • TIM Worker
    • technology: Julia
    • image: crwebservices.azurecr.io/tim-worker:v5.0
    • containers: Multiple containers can be running. Default value is 2 containers
  • Telemetry post-processor
    • technology: Julia
    • image: crwebservices.azurecr.io/tim-telemetry-postprocessor:v0.4
    • containers: 1 container running permanently for entire TIM Engine installation
  • Telemetry server
    • technology: Python 3.7 with Falcon framework
    • image: euwestacrtangentworks01.azurecr.io/tim_telemetry:v2.9
    • containers: 1 container running permanently for entire TIM Engine installation
  • Telemetry worker (Python Celery)
    • technology: Python 3.7 with Celery
    • image: euwestacrtangentworks01.azurecr.io/timtel_celery:v2.9
    • containers: 1 container running permanently for entire TIM Engine installation
  • License loader
    • technology: Python
    • image: euwestacrtangentworks01.azurecr.io/tim-on-premise-license-loader:v1.0
    • containers: 1 container running only on TIM Engine start (container terminates after finishing it's task)
  • Deployment validator
    • technology: Python
    • image: euwestacrtangentworks01.azurecr.io/tim-on-premise-deployment-validator:v1.0
    • containers: 1 container running only on TIM Engine start (container terminates after finishing it's task)

The Docker images listed above are composed to the following container structure by using docker-compose:

DockerContainerStructure.png

Note: Green containers are running permanently, purple containers run only on TIM Engine start and terminate after finishing their task.

Requirements​

To run TIM Engine on-premise, following requirements must be met.

Hardware requirements​

  • CPU: AMD64 or ARMv8 architecture (64-bit), at least 2 cores
  • RAM: at least 8 GB
  • Storage: at least 50 GB of free space
  • Internet access: not required

Software requirements​

  • OS: Linux (Ubuntu 18.04 and newer recommended)
  • Bash
  • Unzip utility (apt-get install unzip)
  • Docker Engine 19.03 and newer (More info)
  • Docker Compose (More info)

Network configuration​

  • Unused port 80 is required by TIM Engine
  • Unused port 5432 is required by TIM Telemetry database
  • Unused port 15672 is required by RabbitMQ Management Plugin
  • If TIM Engine should be accessible from other machines, allow incoming traffic on port 80 TCP (HTTP)
  • If TIM Telemetry database should be accessible from other machines, allow incoming traffic on port 5432 TCP

Other requirements​

  • On-premise TIM installation bundle
  • On-premise TIM License issued by Tangent Works
    • License is in the form of a signed YAML file
    • Please contact support at _support@tangent.works_ to obtain your On-premise TIM License

Installation​

To be able to install TIM on-premise, make sure all requirements are fulfilled and you have received your own On-premise TIM installation (tim-on-premise-v4_4.zip) bundle and On-premise TIM License (tim_license_xy.yaml). Follow steps below to install and activate TIM:

  1. Copy On-premise TIM installation bundle and On-premise TIM License to your machine. Use appropriate method to meet your security policy and preferences.

    • In this example we will use SFTP to transfer files tim-on-premise-v4_4.zip and tim_license_xy.yaml

    • Our machine has a hostname tim_vm, user is ubuntu and we will copy files to /home/ubuntu/

      scp tim-on-premise-v4_4.zip ubuntu@tim_vm:/home/ubuntu/
      scp tim_license_xy.yaml ubuntu@tim_vm:/home/ubuntu/

  2. Now connect to your machine's bash shell

    • In this example we will use SSH

      ssh ubuntu@tim_vm

  3. Change working directory to a directory where tim-on-premise-v4_4.zip and tim_license_xy.yaml is located

    • In our example we will go to /home/ubuntu/

      cd /home/ubuntu/

  4. Unzip tim-on-premise-v4_4.zip archive

    unzip tim-on-premise-v4_4.zip

  5. Copy tim_license_xy.yaml to the unzipped archive to a subfolder tim/licenses/

    • In our example we copy license file to tim_on_premise/tim/licenses/ (absolute path /home/ubuntu/tim_on_premise/tim/licenses/)

      cp tim_license_xy.yaml tim-on-premise-v4_4/tim/licenses/

  6. Change working directory to the unzipped archive

    cd tim-on-premise-v4_4

  7. Add execute permissions to timctl utility

    chmod +x timctl

  8. Start On-premise TIM installation

    ./timctl install -o docker_images -t -l "{LICENSE_KEY}" -u "{ADMIN_EMAIL}" -k "{ADMIN_PASSWORD}"

    Set parameters of the command above to the values that are included in your On-premise TIM License:

    • LICENSE_KEY - license key specified in obtained On-premise TIM license
    • ADMIN_EMAIL - email address of administrator of obtained On-premise TIM license
    • ADMIN_PASSWORD - TIM license admistrator's password

    Note: It can take up to 10 minutes to install On-premise TIM.

  9. Check status of TIM installation

    • Status of all TIM containers:

      ./timctl status

    • Results of deployment tests:

      ./timctl show-tests

TIMCTL utility​

TIMCTL utility can be used to monitor and control your On-premise TIM deployment. To get information about available timctl commands and arguments, use -h command line argument.

To check status of TIM containers, use status argument

./timctl status

To stop TIM, use argument stop

./timctl stop

To start TIM, run timctl with start argument

./timctl start

To restart TIM, use restart argument

./timctl restart

Using TIM deployment tests​

To start deployment tests manually, use run-tests argument

./timctl run-tests

This command starts automated testing utility. To see the results, use show-tests argument

./timctl show-tests

Using TIM​

After successfully completing TIM Engine installation, TIM Engine API is awaiting requests on port 80 (HTTP). You can send request to TIM by using TIM FQDN

  • If accessing TIM from localhost: http://localhost/{version}/api (e.g. http://localhost/v4/api)
  • If accessing TIM from another machine: http://{other_machine_ip_address}/{version}/api

TIM on-premise solution uses TIM Engine in version v4.4. It is also possible to use more general version v4 or latest.

API Reference can be found at http://localhost/v4/swagger-ui.html or http://localhost/v4/redoc.html.

Telemetry​

Each TIM Engine request is logged to TIM Telemetry. To view telemetry records of your TIM Engine on premise installation, you need to access Telemetry Postgres database telemetrydb. Schema of telemetrydb is following:

TelemetryDatabaseModel.png

Access​

To access Telemetry database, use following login informations:

  • Postgres host: localhost
  • Postgres port: 5432
  • Telemetry database name: telemetrydb
  • Database user: timtelemetryuser
  • Password: dETj47MUzkXe4r5H

When successfully connected, you can use SQL queries to get telemetry data.

Example: Getting last 10 telemetry records with user emails and license keys:

SELECT * FROM telemetry
JOIN user ON (telemetry.user_id = user.id)
ORDER BY timestamp_of_request DESC
LIMIT 10;

Backup​

Recommended approach to doing backup is to use pg_dump utility

pg_dump -h localhost -p 5432 -U timtelemetryuser telemetrydb > tim_telemetry.bak

Store file tim_telemetry.bak to secure location to protect your backup.

Uninstallation​

To uninstall TIM Engine, run following command:

Note: this action stops and deletes all containers of TIM Engine.

./timctl uninstall

To uninstall TIM Engine and remove all data, run following command:

Note: this action stops and deletes all containers of TIM Engine and delete ALL data. This cannot be undone! Proceed with caution.

./timctl uninstall -a