Skip to main content

Docker – REST API Setup

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

Configure the Database image:

  • Linux (Hosts) - MariaDB: docker.io/mariadb:10.4
  • Windows - Docker Desktop: mysql:8.0
securosys_sql:
  image: docker.io/mariadb:10.4
  #image: bitnami/postgresql:latest
  #image: mysql:8.0 # uncomment for Windows (Docker Desktop)

Set Database User and Password (MySQL / MariaDB)

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
note
  • Set passwords withouth special-characters and 30-bytes long.
  • It is strongly recommended to define all database passwords during initial setup, as 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

Set Database User and Password (MySQL / MariaDB)​

  • Ensure the username and password match the ones defined in your docker-compose.yml.
### MariaDB (default 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​

If using Securosys CloudHSM, update the following values using the details provided on the HSMaaS - Connectivity Details

##HSM CONFIGURATION
hsm:
  host: 'ch01-api.cloudshsm.com,ch02-api.cloudshsm.com' # REPLACE with the hsm URL or IP
  port: '2300' # REPLACE with HSM JCE-Port
  user: replace-me_hsm-username # REPLACE with your HSM username (PartitionName)
  setupPassword: replace-me_hsm-setupPassword # REPLACE with your HSM SetupPassword
  encryptionPassword: replace-me_db-encryptionPassword # REPLACE it is used to encrypt the hsm user secret, stored in the database

Best to not use special characters in encryptionPassword and is at least 30 bytes long.

Load-Balancing: hsm.host
  • Specify multiple hosts separated by commas, and the RestAPI will randomly select one host, falling back to the others if the first one fails (e.g., hsm.host: 'grimsel.securosys.ch,nufenen.securosys.ch').
  • Provide multiple hosts separated by semicolons, and the RestAPI will always choose the first record, falling back to the others if the first one fails (e.g., 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:

Password: #<ENTER PASSWORD FROM DOWNLOAD-LINK FILE> # if not know, check the Download page.

If you’re unsure of the password location, refer to the Downloads page.

Start the application in detached mode (-d):

docker-compose up -d

Open Swagger​

Open the (Swagger) to interact with the 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 you can follow the guides below.

What's next?​

Last updated on