Getting started ​

This document will walk you through the steps of installing our framework with a sample service and downloading our client component along with an example to access that sample service. Downloading the TSF will come with the following 4 components - Network Service, TSF Server, Register Service, and Management Console. The instructions below will walk you through how to set up each one.

Prerequisites ​

Regardless of which of the below methods you use to start the TSF, the following is a prerequisite.

• An SQL compliant database that has a JDBC driver. (Our Docker image comes with the JDBC Drivers for MySQL and Postgres and our TSF has been tested with both. Our Docker image does not include either of these databases, but you can add either or a different database to the Docker image if you are using Docker. If not using Docker, your server must have access to an SQL-compliant database and, if not one of these two, you will need to download the JDBC driver.)

Our framework can run in the following ways. Based on which of these ways you would like to run the TSF, there are different prerequisites:

Bare metal without Docker (Directly on host machine) ​

• JDK11 or later
• Etcd (instructions for how to install etcd are provided in this documentation)

Docker with JDK inside image (Recommended) ​

• Docker

Etcd and the JDK are bundled inside of the Docker images, so there is nothing special that needs to be installed on the host machine. These Docker images come with JDK Corretto [Amazon's supported open source release]

Docker without JDK inside image (Recommended) ​

• Docker

• JDK11 or later

  Important Notes:

  1. Because the JDK is not inside of the image, the path to the JDK installation on the host machine must be provided at runtime when starting the Docker containers (shown below).
  2. Our Docker images without the JDK have a base of Alpine Linux (the same version of open source Linux that runs in Amazon AWS and supported by Amazon). If you are starting the TSF this way, the java binaries on the host machine MUST be compiled with Alpine Linux, since that is the base OS of our Docker image.

Installing and setup ​

• To start off, create a directory where you will be working / extracting all relevant tars.

  # Mac / Linux
  mkdir -p /Users/$USER/Tessellation/POC/setup
  
  # Windows
  MD C:\Users\%USERNAME%\Tessellation\POC\setup

• Visit our website https://tessellationsoftware.com/verification to download the relevant tars mentioned in the below instructions.

Initially, to get this example working, the TSF will be running with 1 server. If you are using docker, after this example is completed, you can add more instances to the grid. If you are not using docker, starting multiple servers would require multiple machines since multiple TSF servers cannot be started on a single JVM.

Test directly on host machine (without docker) ​

Follow these steps if you wish to start the TSF without docker. If you wish to start the TSF with docker, you can skip this section and go directly here.

Download TSF ​

• Download the appropriate TSF framework tar based on the JDK version in which you would like our jars to be compiled.
  • The JDK that is installed on the host machine must be able to run this JDK version that you select.
• Download the TSF framework example tar
• Extract the contents of the framework tar and the example tar

You should see 4 tars inside of each (which correspond to a bare metal tar that is a component of the TSF along with its example). In other words, in your framework tar, you should see a tsf server tar, a register service tar, a network service tar, and a console tar. And in your framework example tar, you should see a tsf example tar, a register service example tar, a network service example tar, and a console example tar.

• For each of tars mentioned above (8 total), extract their contents into the setup directory you created earlier

# These lines need to be run 4 times for each component of the framework
# along with its example counterpart

cd /Users/$USER/Tessellation/POC/setup
tar -xvf <downloaded directory>/<non-docker tar>
tar -xvf <downloaded directory>/<non-docker example tar>

Before proceeding with the setup instructions, make sure that your workspace looks like the following - in your setup directory, you should now see 8 folders, 4 that are the bare metal components of the TSF, and 4 example folders that correspond to each one.

Start Network Service without docker ​

Since the Network Service uses etcd under the hood, etcd must be installed if not using docker. Follow the steps for installing etcd on your machine for your operating system.

Install etcd on linux

# Download the etcd binary from the official website
wget https://github.com/etcd-io/etcd/releases/download/v3.5.11/etcd-v3.5.11-linux-amd64.tar.gz

# Extract contents of the archive
tar -xvf etcd-v3.5.11-linux-amd64.tar.gz

# Move the etcd and etcdctl into /usr/local/bin 
cd etcd-v3.5.11-linux-amd64
sudo mv etcd /usr/local/bin
sudo mv etcdctl /usr/local/bin

Install etcd on macOS

brew install etcd

Install etcd on windows

• Go to https://github.com/etcd-io/etcd/releases, and scroll down to find the windows download for etcd. Download the zip named https://github.com/etcd-io/etcd/releases/download/v3.5.11/etcd-v3.5.11-windows-amd64.zip (or some similar version).
• Once you download this zip, extract it on your host machine, which should create a folder named etcd-v3.5.11-windows-amd64.
• Go into that directory, and you should see binaries named etcd.exe and etcdctl.exe. Move them into your /usr/local/bin directory so that these commands can be recognized anywhere.

To verify that the etcd installation worked, you should be able to run the following (in any directory) without any errors:

etcdctl version

• To start the example network service for Mac / Linux, execute 👇

sh /Users/$USER/Tessellation/POC/setup/example-network-service/bin/start.sh

• To start the example network service for Windows, execute 👇

\Users\%USERNAME%\Tessellation\POC\setup\example-network-service\bin\start.bat

You should have 1 network service instance running -- You should see the message ready to servce client requests in the console. Keep the network service running in this terminal, and open a new terminal window for the rest of the steps.

Start Register Service without docker (Optional) ​

If you wish to start a singleton grid, then the Register Service is not necessary, and you can skip directly to starting the TSF. Note: this means that the TSF will ALWAYS remain with 1 server, and more cannot be added to the grid. If you may want to add more servers in the future, you should follow the steps below and start the Register Service (even if there is only 1 TSF server in the grid), since then more can be added after.

• To start the example register service for Mac / Linux, execute 👇

sh /Users/$USER/Tessellation/POC/setup/example-register-service/bin/start.sh

• To start the example register service for Windows, execute 👇

\Users\%USERNAME%\Tessellation\POC\setup\example-register-service\bin\start.bat

You should now have 1 register service instance running -- You should see that it starts up and connects to the network service with no errors, however it is waiting for TSF instances to be added to the grid, so you won't see it processing anything (until we get to the next step). Keep the register service running in this terminal, and open a new terminal window for the rest of the steps.

Start TSF without docker ​

• Execute the script provided in download example app at location: example-tsf-app/conf/tsf-init.sql or example-tsf-app/conf/tsf-init-postgres.sql and execute it in your database. (The MySQL script should work with Oracle.) This must be done in the same database that hibernate.xml file identifies. Make sure to use replaceWYourDatabaseName before executing this script. The TSF uses this database to store username, encrypted passwords (and, in the case of secure connections, the DName of the X509 Certiificate) to validate connections of end-user apps or system APIs attempting to connect to the TSF. (If a secure connection and digital signing is being used, it also stores verfied signed messages sent by users for non-repudiation purposes.)

• Open example-tsf-app/conf/hibernate.mysql.cfg.xml or example-tsf-app/conf/hibernate.postgres.cfg.xml file (or use your own) and change connection url to the database where the script was executed and change the username and password to one that has access to the tables created by the script. We support any SQL database and have specifically tested with these two. The proper JDBC driver and database user name and password are to be in this file.
  

• Update the license key property provided to you (in a separate mail) in the tsf.properties file (or tsf-windows.properties if running TSF on Windows machine):

• Open example-tsf-app/conf/overrideInstanceConfig.json, and update the json parameter dbConfigFilePathAndName to be the directory and file name of the hibernate file you will be using as discussed above.

Next, to actually start the TSF, the script to run depends on whether you are starting a singleton grid (without a Register Service) or a grid with a Register Service (Recall the difference in the previous step). If you are running a singleton TSF grid without a Register Service, run the following:

• For Mac / Linux, execute 👇

sh /Users/$USER/Tessellation/POC/setup/example-tsf-app/bin/startSingleton.sh

• For Windows, execute 👇

\Users\%USERNAME%\Tessellation\POC\setup\example-tsf-app\bin\startSingleton.bat

• For Mac / Linux, execute 👇

sh /Users/$USER/Tessellation/POC/setup/example-tsf-app/bin/startGrid.sh

• For Windows, execute 👇

\Users\%USERNAME%\Tessellation\POC\setup\example-tsf-app\bin\startGrid.bat

If you are starting a grid with a Register Service, you should now see that this TSF instance is waiting for the grid to start, which will be done in the following step via the console. If you are starting a singleton grid (without a Register Service), then you should already see that the TSF instance is running -- by the Server is up and running message. Keep the server running in this terminal, and open a new terminal window for the rest of the steps.

Start Console without docker ​

Now it is time to start the Management Console to interact with the grid and ultimately start it. Again, if you are starting a singleton, the Console has no purpose except when shutting down the grid. If you starting a grid, then the Console can be used to interact with it.

• For Mac / Linux, execute 👇

sh /Users/$USER/Tessellation/POC/setup/example-console/bin/start.sh

• For Windows, execute 👇

\Users\%USERNAME%\Tessellation\POC\setup\example-console\bin\start.bat

After this, you should see the Console connect to the Network Service, and display a list of options. If you are running a non-singleton grid, select the 'Start grid' option, and then you should see the status of TSF instance 1 come in as UP_AND_RUNNING after a few seconds - for a singleton grid there is nothing to do here, since the instance is already running from the previous step.

Test Using docker ​

Follow these steps if you wish to start the TSF with docker. Throughout this example, we will need to create volume mappings to pass in certain override configuration files when running the docker containers. Create a folder for these override configuration files using the following:

mkdir -p /Users/$USER/Tessellation/POC/setup/overrides

Download TSF ​

• Download the appropriate TSF framework docker tar based on the following parameters:

  • Platform (linux/amd64 or linux/arm64)
  • JDK version in which jars are compiled
  • Whether to have the JDK bundled inside of the docker images (if yes, the JDK that will be inside of the images will be the same version specified in the previous parameter)

• Extract the contents of the tar

You should see 4 tars inside, each of which correspond to a docker image that is a component of the TSF.

• Load each of these tars into docker images, using the below command for each of the 4 tars.

docker load -i <downloaded directory>/<docker image tar>

Now you should have 4 docker images, corresponding to the tars downloaded in the previous step. To verify this, run docker images in your command window, and they should appear in the resulting list.

E.g. If you downloaded the TSF specifiying the platform as linux/arm64, the JDK version as 11, and to bundle the JDK inside of the docker images, you should have the following images in your local docker after loading the tars:

• tsf/tsf-server:<clientId>-java11-wjdk-<release-version>
• reg/register-service-java11-wjdk:<release-version>
• tsf/tsf-console-java11-wjdk:<release-version>
• ts/network:<release-version>

Note: The Network Service does not use java, so its image is the same regardless of the JDK options above.

Start Network Service with docker ​

• Start the network service container using the following command

docker network create --subnet 10.0.0.0/24 test-tsf

docker run -d -p 23797:2379 --ip 10.0.0.17 --name network-service-1 \
--hostname network-service-1 --rm --network test-tsf -e INSTANCE_NUM=1 \
-e INITIAL_HOST_URLS=network-service-1=http://network-service-1:2380 \
-e CLUSTER_STATE=new ts/network:<release-version>

You should see the network-service-1 container running, and the message ready to servce client requests in its logs.

Start Register Service with docker (Optional) ​

If you wish to start a singleton grid, then the Register Service is not necessary, and you can skip directly to starting the TSF. Note: this means that the TSF will ALWAYS remain with 1 instance, and more cannot be added to the grid. If you may want to add more instances in the future, you should follow the steps below and start the Register Service (even if there is only 1 TSF server in the grid), since then more can be added after.

• Create an override configuration file named /Users/$USER/Tessellation/POC/setup/overrides/reg-svc/overrideGridConfig.json that looks like the following:

{
  "networkServiceEndpoints": ["http://network-service-1:2379"]
}

• If you downloaded the register service image WITH the JDK inside the image, start the register service container using the following command:

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/reg-svc:/home/reg-svc/conf/overrides \
-d --network test-tsf --rm --ip 10.0.0.71 --name register-service-1 \
-e OVERRIDE_GRID_CONFIG=/home/reg-svc/conf/overrides/overrideGridConfig.json \
reg/register-service-java<jdk-version>-wjdk:<release-version>

• If you downloaded the register service image WITHOUT the JDK inside the image, start the register service container using the following command:

  Note: the path inside the container where the jdk will be mapped to INSIDE the container is /tmp/jdk. This value does not matter and can be changed to whatever you want, but the path in the volume mapping MUST match the value provided in the JDK_PATH environment variable. We recommend this path (/tmp/jdk) instead of anything inside of the /usr directory because any unintentional changes to the /usr could create problems.

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/reg-svc:/home/reg-svc/conf/overrides \
-v <path to JDK on host machine>:/tmp/jdk -d --network test-tsf \
--ip 10.0.0.71 --rm --name register-service-1 \
-e OVERRIDE_GRID_CONFIG=/home/reg-svc/conf/overrides/overrideGridConfig.json \
-e JDK_PATH=/tmp/jdk \
reg/register-service-java<jdk-version>-nojdk:<release-version>

You should now have 1 register service instance running -- You should see that it starts up and connects to the network service with no errors, however it is waiting for TSF instances to be added to the grid, so you won't see it processing anything (until we get to the next step).

Start TSF with docker ​

• Download tsf server example tar from the Download screen and extract it on the host machine using the following commands.
  

cd /Users/$USER/Tessellation/POC/setup
tar -xvf <downloaded directory>/<example tsf tar>

This should have created a directory example-tsf-app in your setup directory.

• Execute the script provided in download example app at location: example-tsf-app/conf/tsf-init.sql or example-tsf-app/conf/tsf-init-postgres.sql and execute it in your database. (The MySQL script should work with Oracle.) This must be done in the same database that hibernate.xml file identifies. Make sure to use replaceWYourDatabaseName before executing this script. The TSF uses this database to store username, encrypted passwords (and, in the case of secure connections, the DName of the X509 Certiificate) to validate connections of end-user apps or system APIs attempting to connect to the TSF. (If a secure connection and digital signing is being used, it also stores verfied signed messages sent by users for non-repudiation purposes.)

• Open example-tsf-app/conf/hibernate.mysql.cfg.xml or example-tsf-app/conf/hibernate.postgres.cfg.xml file (or use your own) and change connection url to the database where the script was executed and change the username and password to one that has access to the tables created by the script. We support any SQL database and have specifically tested with these two. The proper JDBC driver and database user name and password are to be in this file.
  

• Update the license key property provided to you (in a separate mail) in the tsf.properties file:

• Next, to create the example image, go to the example-tsf-app directory and edit example-tsf-app/build/Dockerfile
  

• Change line FROM tsf/tsf-server:<clientId>-java<jdk-version>-<wjdk/nojdk>-<release-version> to add your clientId, the release version, and the jdk version of the tsf-server image you downloaded in the first step.
  

• To build the example docker image, execute

sh /Users/$USER/Tessellation/POC/setup/example-tsf-app/build/build.sh

This will create tsf/tsf-server-example:test image. Verify by executing docker images command.

• Create an override configuration file named /Users/$USER/Tessellation/POC/setup/overrides/tsf-server/overrideInstanceConfig.json that looks like the following:

  {
    "networkServiceEndpoints": ["http://network-service-1:2379"],
    "dbConfigFilePathAndName": "/home/tsfuser/tsf-server/conf/<hibernate file you will be using as discussed above>"
  }

  1
  2
  3
  4
  

Finally, start the example app container using following command depending on how you configured your grid to be earlier:

If you downloaded the TSF server image WITH the JDK inside the image, start the TSF server container using the following command:

• If you started a non-singleton (e.g. WITH a Register Service), run the following:

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/tsf-server:/home/tsfuser/tsf/conf/overrides \
-d --network test-tsf --ip 10.0.0.2 --name tsf-instance-1 \
--rm -e INSTANCE_NUM=1 -e SINGLETON=false \
-e OVERRIDE_INSTANCE_CONFIG=/home/tsfuser/tsf/conf/overrides/overrideInstanceConfig.json \
-p 9081:9080 tsf/tsf-server-example:test

• If you started a singleton grid (e.g. WITHOUT a Register Service), run the following:

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/tsf-server:/home/tsfuser/tsf/conf/overrides \
-d --network test-tsf --ip 10.0.0.2 --name tsf-instance-1 \
--rm -e INSTANCE_NUM=1 -e SINGLETON=true \
-e OVERRIDE_INSTANCE_CONFIG=/home/tsfuser/tsf/conf/overrides/overrideInstanceConfig.json \
-p 9081:9080 tsf/tsf-server-example:test

If you downloaded the TSF server image WITHOUT the JDK inside the image, start the TSF server container using the following command:

Note: the path inside the container where the jdk will be mapped to INSIDE the container is /tmp/jdk. This value does not matter and can be changed to whatever you want, but the path in the volume mapping MUST match the value provided in the JDK_PATH environment variable. We recommend this path (/tmp/jdk) instead of anything inside of the /usr directory because any unintentional changes to the /usr could create problems.

• If you started a non-singleton (e.g. WITH a Register Service), run the following:

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/tsf-server:/home/tsfuser/tsf/conf/overrides \
-v <path to JDK on host machine>:/tmp/jdk -d --network test-tsf --ip 10.0.0.2 \
--rm --name tsf-instance-1 -e JDK_PATH=/tmp/jdk -e INSTANCE_NUM=1 \
-e SINGLETON=false -e OVERRIDE_INSTANCE_CONFIG=/home/tsfuser/tsf/conf/overrides/overrideInstanceConfig.json \
-p 9081:9080 tsf/tsf-server-example:test

• If you started a singleton grid (e.g. WITHOUT a Register Service), run the following:

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/tsf-server:/home/tsfuser/tsf/conf/overrides \
-v <path to JDK on host machine>:/tmp/jdk -d --network test-tsf --ip 10.0.0.2 \
--rm --name tsf-instance-1 -e JDK_PATH=/tmp/jdk -e INSTANCE_NUM=1 \
-e SINGLETON=true -e OVERRIDE_INSTANCE_CONFIG=/home/tsfuser/tsf/conf/overrides/overrideInstanceConfig.json \
-p 9081:9080 tsf/tsf-server-example:test

If you were running MySQL or another database as a docker container, that must also have "--network test-tsf" in its run command.

If you are starting a grid with a Register Service, you should now see that this TSF instance is waiting for the grid to start, which will be done in the following step via the console. If you are starting a singleton grid (without a Register Service), then you should already see that the TSF instance is running -- by the Server is up and running message in its logs.

Start Console with docker ​

Now it is time to start the Management Console to interact with the grid and ultimately start it. Again, if you are starting a singleton, the Console has no purpose except when shutting down the grid. If you starting a grid, then the Console can be used to interact with it.

• Create a properties file named /Users/$USER/Tessellation/POC/setup/overrides/console/console.properties that looks like the following:

  NetworkServiceEndpoints=["http://network-service-1:2379"]

  1
  

• If you downloaded the console service image WITH the JDK inside the image, start the console container using following command:

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/console:/home/tsfuser/console/overrides \
-di --network test-tsf --ip 10.0.0.81 --name console-1 -e CONSOLE_ID=1 \
--rm -e PROPERTIES_FILE=/home/tsfuser/console/overrides/console.properties \
tsf/tsf-console-java11-wjdk:<release-version>

• If you downloaded the console service image WITHOUT the JDK inside the image, start the console container using following command:

  Note: the path inside the container where the jdk will be mapped to is /tmp/jdk. This value does not matter and can be changed to whatever you want, but the path in the volume mapping MUST match the value provided in the JDK_PATH environment variable. We recommend this path (/tmp/jdk) instead of anything inside of the /usr directory because any unintentional changes to the /usr could create problems.

docker run -v /Users/$USER/Tessellation/POC/setup/overrides/console:/home/tsfuser/console/overrides \
-v <path to JDK on host machine>:/tmp/jdk -di --network test-tsf \
--ip 10.0.0.81 --name console-1 -e JDK_PATH=/tmp/jdk -e CONSOLE_ID=1 \
--rm -e PROPERTIES_FILE=/home/tsfuser/console/overrides/console.properties \
tsf/tsf-console-java11-nojdk:<release-version>

To actually interact with the console, exec into the console container by executing the following (Alternatively, if using Docker Desktop, click on the console-1 container and select Exec in the top menu bar):

docker exec -it console-1 bash

Once you have started a shell inside the console image, run the following command:

• To start the console if using the Docker image WITH the JDK inside, run:

sh start.sh 1

• To start the console if using the Docker image WITHOUT the JDK inside, run:

sh start.sh 1 <path to JDK INSIDE the container>

Where <path to JDK INSIDE the container> = /tmp/jdk in the example above.

After this, you should see the Console connect to the Network Service, and display a list of options. If you are running a non-singleton grid, select the 'Start grid' option, and then you should see the status of TSF instance 1 come in as UP_AND_RUNNING after a few seconds - for a singleton grid there is nothing to do here, since the instance should already have started from the previous step.