Installing Cantara

Please send these instructions to your validator operator for installaiton.

Main contact for technical/app assistance from The Tie:
Ben Latz (CTO) - ben@thetie.io or @benlatz on TG
Join the Cantara support Slack‍

Disclaimer: Everyone has their own validator configurations and setups whether you're using Kubernetes or Docker, nginx or traefik, Auth0 or Keycloak, etc. These docs are natively for Kubernetes + nginx + Auth0 because that's what we use, but we're collecting code snippets from users for all variations to help provide additional documentation. Please join the Slack for help from others who share your same setup stack, in addition to our direct support.

1. Download this whole folder and upload the DAR files in the dars folder to your validator. https://drive.google.com/drive/folders/1uAiP2XJzb76Gsq20PDrXxO1lwDc4UBMw?usp=sharing
   
   If you don’t already have an existing process to upload DARs, you can use the script attached to folder and follow these steps:
   
   a. Forward your participant node to localhost:5002
   
   Ex: using kubectl with kubernetes:
   kubectl port-forward {pod-name} 5002:5002 -n {namespace}
   
   b. To use this local script example, you’ll grab an admin JWT token to access your validator api (on Auth0 you can get it from the Test tab under the machine-to-machine Validator API application or generate it via their API endpoints) and insert it to the upload-dar-cantara.sh script as the jwt_token variable at the top and run it. As this is a local script, we never see this token, and you can choose to upload the DAR however way you want, this script is just an example if you haven’t done it before.

2. Add an ingress configuration to expose your validator api and ledger api under api.YOUR_HOST_DOMAIN (or any subdomain you choose). You may already have these services exposed from other applications like wallet or utility, but you need 1 base url to have both, so you can add something like this in a typical ingress config (similar to however the wallet UI was installed for example).

_{- host: api.YOUR_HOST_DOMAIN
     http:
       paths:
         - path: /api/validator
           pathType: Prefix
           backend:
             service:
               name: validator-app
               port:
                 number: 5003
         - path: /api/json-api
           pathType: Prefix
           backend:
             service:
               name: participant
               port:
                 number: 7575}

3. Also add these annotations to the ingress under metadata.annotations (this solves CORS issues when the application calls the apis above) - this is for nginx, but traefik uses middleware for CORS. Requests are made directly from your browser, which is what causes CORS issues without proper headers. Local browser calls ensure your Canton Party JWT never touches our infrastructure and also works with your existing IP address if your infrastructure is protected by whitelisting IPs.(https://cantara.thetie.io for mainnet, https://cantara-testnet.thetie.io for testnet)

_{metadata:
   name: {your ingress name here}
   namespace: {your namespace, probably validator}
   annotations:
     nginx.ingress.kubernetes.io/enable-cors: "true"
     nginx.ingress.kubernetes.io/cors-allow-origin: "https://cantara.thetie.io"
     nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, PATCH, DELETE, OPTIONS"
     nginx.ingress.kubernetes.io/cors-allow-headers: "Origin, Authorization, Content-Type, Accept"
     nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
     nginx.ingress.kubernetes.io/cors-max-age: "3600"}

‍

4. Create or modify an OIDC Application with the following:
   
   1. Application type is a Single Page Web Application (for Auth0) or Public (for Keycloak)
   2. Add the following callback_urls:
      https://cantara-testnet.thetie.io, https://cantara-testnet.thetie.io/auth/canton/callback,
      https://cantara.thetie.io,
      https://cantara.thetie.io/auth/canton/callback

5. Log into https://cantara-testnet.thetie.io for testnet or https://cantara.thetie.io for mainnet with your work Google or Microsoft account. If someone on your team has already gone through the setup process, have them invite you to their existing team (and you can skip Step 6 and 7).
   _{Note: Cantara has a separate authentication layer of your normal work email sign-on, separate from the Canton party authentication. This will enable you to add teammates with read-only access who can’t sign into the party directly, and also more easily manage/switch between multiple Canton parties (these features coming soon). The OIDC configuration is saved at the Team level so no other team members need to enter that information.}
6. Go to Team Settings from the left navigation and input your OIDC configuration, which will allow you to sign in with your Canton party. Either your validator operator has already put this in and invited you to the team, or if you are starting from scratch yourself, please get the values from your validator operator.
7. In Team Settings, also add your Canton API url which is the full base url you specified in the ingress configuration. In the example script above that would be https://api.YOUR_HOST_DOMAIN
8. Sign into your Canton party using the button in the left navigation. If nothing happens when you click it, that may mean your configuration isn’t valid or something else is wrong - please reach out to us for help debugging (to Ben or on the Cantara Slack)
9. Share the party id (can copy it from the left navigation) with The Tie or whoever is issuing a subscription. Once the subscription offer is issued, it’ll show as an Offer to Accept on the Subscriptions page.

‍