Reference Deployment

21 Travel Rule is a software solution for FATF’s Travel Rule by 21 Analytics.

These instructions only work if you have a valid 21 Travel Rule license, which comes with a username and password to access our Docker Registry.

If you get stuck with the deployment instructions then please refer to our Troubleshooting section where common usage errors are clarified.

Hardware Requirements

We recommend the following minimum for operating the 21 Travel Rule software:

  • 2 CPU 2198 MHz
  • 2 GB RAM
  • 40 GB Disk

The hardware requirements depend the number of transactions you send & receive.

The above disk requirement includes 20 GB dedicated to the file storage service. You may in- or decrease this quota by modifying the arguments to the seaweedfs service.

Software Requirements

To run 21 Travel Rule the following software needs to be installed:

  • Docker
  • Docker Compose (version 2.x or higher)
  • git

Any operating system which can run Linux Docker containers will work.

Deployment with Docker Compose

First, pull this git repository with

git clone https://gitlab.com/21analytics/21-travel-deployment.git

Second, log in to our Docker Registry using the username / password that you have obtained from us by executing the following command:

docker login registry.21analytics.ch -u YourUsername

Then adjust the domain names in the Caddyfile to enable HTTPS. You probably want to commit your changes to the Caddyfile to simplify upgrades later:

git add Caddyfile
git commit -m "Caddyfile: Set domain"

NOTE: Caddy will automatically set up HTTPS using the ACME protocol. The only pre-requisite is to configure your domains in the Caddyfie after you have registered them with your domain name registrar. The completion of the ACME challenge can take several minutes. Therefore, please allow for some time for the HTTPS auto-setup to complete.

After that, you can spin up your instance with the docker-compose file as shown below. The first time you run those commands the database access passwords are initialised. Therefore, you are free to choose those passwords. We recommend generating cryptographically secure passwords with your chosen key management solution.

After the first initialisation, the environment variables still need to be set to successfully start the platform. The POSTGRES_PASSWORD can be omitted after the first initialisation. Instead of exporting the environment variables you can use a .env file, see here. Also, the pg16_data folder needs to be created where the application data is persisted.

export POSTGRES_PASSWORD=secret_password_1 # only required for init
export AUTOD_DB_PW=secret_password_2
export AOPD_DB_PW=secret_password_3
export TRPD_DB_PW=secret_password_4
export KEYCLOAK_DB_PW=secret_password_5
export KEYCLOAK_ADMIN=your_keycloak_admin_username
export KEYCLOAK_ADMIN_PASSWORD=secret_password_6
export TRAVEL_LOG=info
mkdir pg16_data
docker compose up -d

Allow approximately three minutes for all services to start up.

Once the services are up and running, a user can be created by accessing the graphical user interface. After the first login, the user is redirected to the settings page where further details should be configured.

User Management

The reference deployment uses a Keycloak service to manage user accounts. Please refer to the Keycloak page for more information.

Logging

All our services emit log messages. The log level can be adjusted by setting the TRAVEL_LOG environment variable. Starting with the least verbose level the available log levels are:

  1. error
  2. warn
  3. info
  4. debug
  5. trace

where info is the default log level. TRAVEL_LOG=debug increases the logging level to debug.

Furthermore, it is possible to selectively adjust the logging level for certain modules only (the module names can be obtained from existing logging output), e.g. to increase the logging level for HTTP traffic TRAVEL_LOG=tower_http::trace=debug should be set.

Putting it all together the services can be run with adjusted logging level for HTTP traffic like demonstrated in the following command.

TRAVEL_LOG=tower_http::trace=debug docker compose up -d

Graphical User Interface

The graphical user interface can be accessed as configured in the Caddyfile. It needs to be served from the root path /.

Upgrade

For an upgrade from version 7.0.0 to version 7.1.0 please refer to our upgrade guide.

APIs Exposed by Caddy Reverse Proxy

Here, we document the API endpoints that require to be publicly accessible. Our reference Caddy configuration in the Caddyfile already sets up everything accordingly. This is meant as a reference for firewall and WAF (Web Application Firewall) configuration.

Travel Rule Protocol (TRP):
443 (HTTPS) at /transfers and /transfers/
TCP Incoming and Outgoing. This has to be accessible for your counterparty VASPs.

AOPP 443 (HTTPS) at /proofs/
TCP, incoming only. This has to be accessible for your customers.

Working with OpenShift/Kubernetes

Disclaimer: we don't offer support for deployments on OpenShift or Kubernetes due to the large diversity of possible architectures. However, we have found that our reference deployment offers a helpful guideline for deployments on OpenShift/Kubernetes. Therefore, we provide some hints below for how the reference deployment can be efficiently transformed for use on OpenShift or Kubernetes.

Converting the docker-compose.yml

You can use the kompose tool to convert the docker-compose.yml. Often, the generated files need some manual adjustments, e.g. you might want to remove the caddy reverse proxy service because you are already running a different solution.

Configuring Your Reverse Proxy

You very likely have a reverse proxy running in your cluster already. The Caddyfile can be inspected to extract configuration details you need to apply for your reverse proxy.

Using an Existing Postgres Database

The init.db script can be inspected to extract the required configuration for Postgres (users, passwords, schemas, permissions). As a consequence the database connection URLs that are passed to the 21 Travel Rule services need to be changed.