Utility Setup (Docker Compose)¶

This document outlines the steps required to configure your Docker-Compose-based setup to work with the DA Utilities. This is assuming that you are following the official splice documentation.

Update nginx.conf¶

Create a new entry in the nginx.conf file (splice-node/docker-compose/validator/nginx.conf) for the utility. This should mimic the syntax of the existing entries for wallet, ans, etc.

http {
  ...
  server {
    listen 80;
    server_name utility.localhost;

    location /api/validator/ {
      rewrite ^\/(.*) /$1 break;
      proxy_pass http://validator:5003/api/validator;
    }

    location /api/json-api {
      rewrite ^\/(.*) /$1 break;
      proxy_pass http://participant:7575/;
    }

    location / {
      proxy_pass http://utility-ui:8080/;
    }
  }
}

Also in nginx.conf create a new entry to expose the GRPC port (which will be used to upload DARs to the participant).

server {
  listen       5002 http2;
  server_name  127.0.0.1;

  location / {
    grpc_pass grpc://participant:5002;
  }
}

Update compose.yaml¶

Please make the following changes to the compose.yaml file:

In order to avoid the necessary JSON API path rewrite, add the following environment variable to the participant

participant:
...
  environment:
  ...
    - CANTON_PARTICIPANT_JSON_API_SERVER_PATH_PREFIX=/api/json-api

Expose the following ports on the participant

participant:
  ports:
    - "5002:5002"
    - "7575:7575"

These correlate to the following:

5002 : Admin API
7575 : JSON API

Add a brand new entry for the Utility UI

utility-ui:
  image: "digitalasset-canton-network-utility-docker.jfrog.io/frontend:${FRONTEND_IMAGE_VERSION}"
  environment:
    - AUTH_AUTHORITY=${AUTH_AUTHORITY}
    - AUTH_CLIENT_ID=${AUTH_CLIENT_ID}
    - AUTH_AUDIENCE=${AUTH_AUDIENCE}
    - UTILITY_APP_OPERATOR_PARTY_ID=${UTILITY_APP_OPERATOR_PARTY_ID}
  depends_on:
    - participant
    - validator
  networks:
    - ${DOCKER_NETWORK:-splice_validator}

Please refer here <utility-setup.html#determine-the-utility-operator-party> to find the correct values for the Operator Party ID.

Ensure that the nginx service depends on the newly added utility-ui

  nginx:
...
    depends_on:
...
      - utility-ui

Auth¶

Set up Auth¶

The utilities require Auth to be configured in order to work. This means that you need to follow the steps outlined [here](https://dev.global.canton.network.digitalasset.com/validator_operator/validator_compose.html#configuring-authentication)

These steps have you enter the relevant values to the env file located at splice-node/docker-compose/validator/.env.

You also need to add and populate the following env variables, which relate to the Utility:

#Utility
AUTH_AUTHORITY=${AUTH_URL}
OIDC_AUTHORITY_URL=${AUTH_URL}
AUTH_AUDIENCE=${LEDGER_API_AUTH_AUDIENCE}
OIDC_AUTHORITY_LEDGER_API_AUDIENCE=${LEDGER_API_AUTH_AUDIENCE}
VALIDATOR_CLIENT_SECRET=${VALIDATOR_AUTH_CLIENT_SECRET}
VALIDATOR_CLIENT_ID=${VALIDATOR_AUTH_CLIENT_ID}
CNS_UI_CLIENT_ID=${ANS_UI_CLIENT_ID}
AUTH_CLIENT_ID=
UTILITY_APP_OPERATOR_PARTY_ID=
FRONTEND_IMAGE_VERSION=

Please note:

AUTH_CLIENT_ID is referring to the Auth client that is created specifically for the Utility UI as described here
UTILITY_APP_OPERATOR_PARTY_ID is specific to the network that you are deploying to, and can be found here

Enable auth¶

When following the documentation to launch your node, ensure that you launch your node using the -a flag. (splice-node/docker-compose/validator/start.sh)

./start.sh -s "<SPONSOR_SV_URL>" -o "<ONBOARDING_SECRET>" -p "<party_hint>" -m "<MIGRATION_ID>" -w -a

Upload DARs¶

Once you have succesfully launched the node (all pods are reporting as healthy) you can proceed to upload DARs using the DAR upload script. This can be found in here.

Once the setup is complete, you should be able to access the utility UI at http://utility.localhost.