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.

networks:
  vaultcode_network:
    driver: bridge

volumes:
  vaultcode_db_data:
    driver: local

services:

  vaultcode_db:
    image: bitnami/postgresql:latest
    container_name: "vaultcode_db"
    restart: unless-stopped
    environment:
      POSTGRESQL_DATABASE: vaultcode
      POSTGRESQL_USERNAME: vaultcode
      POSTGRESQL_PASSWORD: changeme_vaultcode_pass
      POSTGRESQL_POSTGRES_PASSWORD: changeme_admin_pass
    volumes:
      - vaultcode_db_data:/bitnami/postgresql
    ports:
      - "5432:5432"
    networks:
      - vaultcode_network

  vaultcode:
    image: securosys.jfrog.io/vault-code/securosys-vault-code:latest
    container_name: "vaultcode"
    restart: unless-stopped
    environment:
      # Select the application profile. This should match the "xyz" in the "application-xyz.yml" filename.
      - spring.profiles.active=vault-code-local
    volumes:
      - "./config-files:/app/vault-code/config:ro"
      - "./logs:/app/vault-code/logs"
    cap_add:
      - NET_ADMIN # needed to manage firewall rules
    depends_on:
      - vaultcode_db
    ports:
      - "8080:8080"
    networks:
      - vaultcode_network

Simulator mode

In simulator mode, set spring.profiles.active=vault-code-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: 'vault_code_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.

• For additional configuration options, see the "Configuration" section. For example, learn how to configure the Execution Partition.
• 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.