Installation

danger

This page describes how to install VaultCode on an external Docker host, outside of the HSM. This is intended for testing purposes only!

Start by downloading the example configuration files. The ZIP file contains examples for the docker-compose.yml and the application.yml files. Extract the ZIP file to a directory on your Docker host.

Docker Compose

First, use Docker Compose to define the containers that need to run.

Below is an example of the docker-compose.yml file. Copy this example to your host and fill it out with your custom values.

services:
  vaultcode_db:
    image: bitnami/postgresql:latest
    container_name: "vaultcode_db"
    volumes:
      - vaultcode_db:/bitnami/postgresql
    environment:
      # REPLACE with your credentials
      - POSTGRES_USER: replace-me_db-username
      - POSTGRES_PASSWORD: replace-me_db-password
      - POSTGRESQL_POSTGRES_PASSWORD: replace-me_admin-db-password
      - POSTGRES_DB: vaultcode

  vaultcode:
    container_name: "vaultcode"
    image: securosys.jfrog.io/vault-code/securosys-vault-code:latest
    restart: always
    volumes:
      - "./config:/app/vaultcode/config"
      - "./logs:/app/vaultcode/logs"
    environment:
      - SPRING_PROFILES_ACTIVE=local                    # REPLACE, based on the environment you are running
      - ALLOWED_DOMAINS=localhost                       # REPLACE with a list of allowed domains
      - ALLOWED_IPS=0.0.0.0                             # REPLACE with a list allowed IPs
      - logging.config=/app/vaultcode/config/logback.xml # Choose log level inside file
    depends_on:
      - vaultcode_db

Simulator mode

In simulator mode, set SPRING_PROFILES_ACTIVE=simulator.

Application config

The ZIP downloaded above also contains multiple application-vault-code-xyz.yml example files in the config-files folder. For running with a connected HSM Partition, use the application-vault-code-local.yml file. For running in simulator/demo mode without an HSM Partition, use the application-vault-code-simulator.yml file.

Copy the relevant application-vault-code-xyz.yml file and fill it out with your custom values.

Below is an example of the application-vault-code-local.yml. See the files shipped in the ZIP file for the full reference, in particular see the inline comments.

spring:
  datasource:
    url: jdbc:postgresql://vaultcode_db:5432/vaultcode?allowPublicKeyRetrieval=true&useSSL=false
    username: replace-me_db-username                             # REPLACE according to the `POSTGRESQL_USERNAME` in the docker-compose.yml file
    password: replace-me_db-password                             # REPLACE according to the `POSTGRESQL_PASSWORD` in the docker-compose.yml file

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: 'changeme_partition_name'
  setupPassword: 'changeme_setup_password'
  encryptionPassword: 'changeme_user_secret_encryption_password'
  proxyUser: 'changeme_cloudhsm_proxy_user'
  proxyPassword: 'changeme_cloudhsm_proxy_password'
  attestationKeyName: 'attestation-key'

vaultcode:
  keys:
    # Key to sign results
    output:
      label: output_key_vaultcode
    evidence:
      label: environment_key_vaultcode
    timestamp:
      label: timestamp_iso_key_vaultcode
    # Key to decrypt uploaded JARs
    encrypt:
      label: encrypt_key_vaultcode

tip

VaultCode is a Spring Boot application. In Spring Boot the config naming scheme is application-{profile}.yml.

You should always specify configurations using such as profile, and then specify the profile in the SPRING_PROFILES_ACTIVE environment variable. Don't override the base configuration.

Simulator mode

When running in simulator mode:

• Use the application-vault-code-simulator.yml example.
• Set vaultcode.demo to true. Then VaultCode will ignore the hsm: section.

  vaultcode:
    demo: true
    # other lines omitted

• Alternatively, delete the hsm: section.

Note that in simulator mode, the keys do not have an attestation when calling GET /api/v1/get_public_key (see below).

Start the container

Log in to the Securosys container registry:

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

You will be prompted for a password. You can find the password in the Downloads section.

Then start the containers:

docker compose up --detach

What's Next

Congratulations, you have set up VaultCode on an external host! You can now begin your testing by loading and running custom executables.

• Install VaultCode in production.
• Upload and run JARs.
• Read the samples:
  • Look into the Blockchain use case to automatically approve transactions below a certain amount.
  • Review other executable samples provided by Securosys.