Skip to main content

Install the TSB with Docker

info

This page is only relevant if you want to use an on-premise TSB. If you use the TSB from the Securosys Cloud, you can skip this page.

This guide walks you through setting up the REST API using Docker and Docker Compose. It assumes that the following prerequisites are already installed and configured:

What This Guide Covers​

This step-by-step guide will help you set up the REST API in a development environment using Docker:

  1. Download Configuration Files
  2. Configure Docker Compose
  3. Configure the REST API
  4. Start and Test the Application

Step 1: Download configuration files​

Head to the Downloads page to get instructions on how to get the software and credentials.

Step 2: Configure Docker Compose​

Unzip the configuration-files and open the docker-compose.yml file.

nano docker-compose.yml

Edit the file depending on your preferred database:

Select the PostgreSQL container image:

securosys_sql:
  image: mariadb:11.8
  #image: mysql:8.0 # uncomment for Windows (Docker Desktop)

Define the volume that is used to persist data across container restarts:

volumes:
  - securosys_sql_data:/var/lib/mysql

Define the database users and passwords:

environment:
# Configuration for MySQL / MariaDB
- MYSQL_USER=replace-me_db-username                 # REPLACE with your credentials
- MYSQL_PASSWORD=replace-me_db-password             # REPLACE with your credentials, ${MARIADB_PASSWORD}  # Use environment variable for password security
- MYSQL_DATABASE=securosys
- MYSQL_PORT=3306
- MYSQL_ROOT_PASSWORD=replace-me_db-root-password   # REPLACE with your credentials
- MYSQL_LOWER_CASE_TABLE_NAMES=0
tip
  • Set passwords without special characters and 30-bytes long.
  • It is strongly recommended to define all database passwords before starting the first container. Changing them later may lead to connection issues.
  • Consider adding a restart: always policy under services.securosys_sql in docker-compose.yml to ensure the SQL server automatically restarts on failure or host reboot.

Step 3: Configure the REST API​

Open the application configuration file:

nano config-files/application-local.yml

Configure the Database Connection​

Configure the TSB with the username and password for the database (that you defined above in your docker-compose.yml). Also define the URL under which the TSB can reach the database.

spring:
  datasource:
    url: jdbc:mariadb://securosys_sql:3306/securosys?allowPublicKeyRetrieval=true&sslMode=false
    #url: jdbc:mariadb://securosys_sql:3306/securosys?sslMode=verify-ca&trustStore=/etc/app/config/truststore.jks&trustStorePassword=change-it
    username: replace-me_db-username # REPLACE according to the `MYSQL_USER` in the docker-compose.yml file
    password: replace-me_db-password # REPLACE according to the `MYSQL_PASSWORD` in the docker-compose.yml file

Configure the HSM Connection​

Configure the connectivity details to specify where the TSB can reach the HSM and which HSM partition the TSB should use.

For details, see the Connectivity Details page. You should have received these values from your HSM administrator.

The only exception is the encryptionPassword, which you need to generate yourself. A randomly generated, 32-character, alphanumeric value is recommended. This value is used to encrypt the HSM User Secret before storing it in the database.

hsm:
  host: 'ch01-api.cloudshsm.com,ch02-api.cloudshsm.com'
  port: '2300'
  user: replace-me_hsm-username
  setupPassword: replace-me_hsm-setupPassword
  encryptionPassword: replace-me_db-encryptionPassword
tip

To enable load balancing, the hsm.host setting accepts the following format:

  • Multiple hosts separated by commas: The TSB will randomly select one host, falling back to the others if one fails. For example: hsm.host: 'grimsel.securosys.ch,nufenen.securosys.ch'.
  • Multiple hosts separated by semicolons: The TSB will always choose the first record, falling back to the others if the first one fails. For example: hsm.host: 'grimsel.securosys.ch;nufenen.securosys.ch'.

Step 4: Start the Application​

Log in to the container registry:

docker login securosys.jfrog.io -u robot.reader.tsb

You will be prompted for a password. You can obtain the password via the Downloads page.

Start the application:

docker compose up --detach

The container should start up.

Open the (Swagger) to interact with the REST API in your browser: http://localhost:8080/swagger-ui/index.html

Test with CURL​

curl http://localhost:8080/v1/licenseInfo

Response:

{"clientFlags":["IMPORT","EXPORT","EXTRACT","KEY_AUTH","REST_API","TSB_ENGINE","EXTERNAL_STORAGE","DESTROY_OBJECTS","EXPORT_LOGS","EXTENDED_KEY_ATTRIBUTES","BTC","ETH","RIPPLE","IOTA","ROOT_KEY_STORE","TIMESTAMP_SERVICE","USEABLE_OBJECTS","CARDANO","PERSISTENT_EXTERNAL_OBJ","KYBER","DILITHIUM","SPHINCSPLUS","LMS","XMSS"]}

Listing Keys:

curl -v http://localhost:8080/v1/key

Response:

['attestation-key', 'timestamp-key']
Development-Only Configuration

This guide outlines a default setup of the REST API without HTTPS and without API authentication.
It is intended for development and testing purposes only and must not be used in production environments.

To harden the application, follow the post-installation guide.

What's next?​

Get started withCloudHSM for free.
Other questions?Ask Sales.
Last updated on
Feedback
Need help?