{"templateId":"markdown","versions":[{"version":"v1.43","label":"v1.43 LTS","link":"/products/custody/v1.43/deployment/install/installation","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.42","label":"v1.42 STS","link":"/products/custody/v1.42/deployment/install/installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.41","label":"v1.41 STS","link":"/products/custody/v1.41/deployment/install/installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/deployment/install/installation","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/deployment/install/installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/deployment/install/installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/deployment/install/installation","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Installation and initialization","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"installation-and-initialization","__idx":0},"children":["Installation and initialization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This phase covers the core technical execution of the on-premise deployment. Before starting, ensure you have completed all prerequisite planning and provisioning:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have provisioned, networked, and made accessible all infrastructure (database, message queue, HSM). (See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/deployment/install/helm-charts"},"children":["Installation environment setup"]},".)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have access to ","Ripple Custody (Vault)"," container images (either directly from Ripple's registry or mirrored to your private registry)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have verified all container image signatures using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cosign"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have prepared your deployment workstation with Helm, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kubectl"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cosign"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will not deploy the entire platform at once. The installation is a multi-stage process. First, deploy the core API. Then use that API to initialize the security components. Finally, use the output of that initialization to deploy the rest of the platform."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The installation will follow these 8 steps:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify prerequisites:"]}," Confirm you have completed ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/deployment/install/helm-charts"},"children":["Installation environment setup"]}," and have the Helm charts ready."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initial configuration:"]}," Configure your own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," with all known prerequisites (DB, MQ, registry, etc.) but leave the secure components disabled."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deploy core services:"]}," Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["helm install"]}," to deploy the user-facing services (API, Web UI, OIDC/Auth)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deploy and initialize the notary:"]}," Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["helm upgrade"]}," to deploy the notary. Then, make a Genesis API call to force the notary to generate its master key. Save the public key from this call."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check progress:"]}," After step 4, you should be able to login to Web UI."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deploy vault and ledgers:"]}," Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["helm upgrade"]}," to deploy the vault (configured with the notary's public key) and all your blockchain indexers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Register your vault:"]}," Manually register the deployed vault instance via the Web UI or API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify your installation:"]}," Create a blockchain account to confirm all components are operational."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-verify-prerequisites","__idx":2},"children":["Step 1: Verify prerequisites"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Before you begin:"]}," This step assumes you have completed ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/deployment/install/helm-charts"},"children":["Installation environment setup"]},", including:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Setting up your deployment workstation with Helm, kubectl, and cosign"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtaining and verifying all container images"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtaining the Helm chart package from Ripple"]}]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unpack the Helm chart package on your deployment workstation:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"tar -xvf ripple-custody-helm-charts-vX.Y.Z.tgz\ncd ripple-custody\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a custom YAML configuration file (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},") using one of the provided example files as a starting point. This file becomes your single source of truth for deployment settings."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not set any sensitive data in this file; use a dedicated Secrets Manager or Kubernetes Secrets instead."]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-initial-productionyaml-configuration","__idx":3},"children":["Step 2: Initial production.yaml configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before your first deployment, edit your configuration file (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},") to connect to the infrastructure prerequisites you provisioned earlier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At this stage, you only configure the known items. You enable the notary, vault, and indexers sections in later steps."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key configuration sections:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\n\n# 1. Container Registry Configuration\n# Option A: Direct connection to Ripple's registry (standard)\nharmonize:\n  repository:\n    base: \"metaco.azurecr.io/custody\"\n    pullSecrets:\n      - \"metaco-creds\"  # Kubernetes secret with Ripple registry credentials\n\n# Option B: Private registry (if you mirrored images)\n# harmonize:\n#   repository:\n#     base: \"my-artifactory.my-bank.com/harmonize\"\n#     pullSecrets:\n#       - \"my-registry-pull-secret\"\n\n# 2. Network & TLS Configuration\n# Define the public-facing hostnames for your services\n  urls:\n    base: \"custody.my-bank.com\"  # Base URL for all subdomains\n    tls: true  # Ensure TLS is enabled for production\n\n    # These URLs will automatically use the base URL and defined subdomains:\n    # frontend: custody.my-bank.com\n    # api: api.custody.my-bank.com\n    # auth: auth.custody.my-bank.com\n\n# 3. Database (PostgreSQL) Connection\n  postgresql:\n    host: \"db-custody.my-bank.local\"\n    port: \"5432\"  # Must be a string\n    database: \"custody_db\"\n    username: \"custody_user\"\n    sslmode: \"verify-full\"  # Recommended for production\n    # NOTE: Password should be injected via Kubernetes secret or external secrets manager\n\n# 4. Message Queue (RabbitMQ) Connection\n  externalAmqp:\n    enabledForCoreComponents: true\n    host: \"mq-custody.my-bank.local\"\n    port: 5671  # TLS port\n    username: \"custody_mq_user\"\n    vhost: \"harmonize\"\n    sslEnabled: true\n    existingSecret: \"mq-password-secret\"  # Reference to Kubernetes secret\n\n# 5. Disable Secure Components (you enable these in later steps)\n  notary:\n    protocol: grpc  # Set protocol but keep disabled\n\ncomponents:\n  notary:\n    enabled: false  # Will enable in Step 4\n\nharmonize:\n  vaults:\n    \"00000000-0000-0000-0000-000000000000\":\n      enabled: false  # Will enable in Step 6\n\n  # Indexers - all disabled initially\n  ledgers:\n    bitcoin-mainnet:\n      enabled: false\n    ethereum-mainnet:\n        enabled: false\n    # ... ensure all other ledgers are set to enabled: false\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note on production.yaml file size:"]}," In production deployments, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," file can exceed 3000 lines. It contains detailed configuration for all components, ledgers, and environments. This guide shows simplified examples for clarity. For complete configuration examples, contact your Ripple liaison."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-deploy-the-core-services","__idx":4},"children":["Step 3: Deploy the core services"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your first deployment will only bring up the \"Core\" services (API, Web UI, OIDC/Auth, and related backends)."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From your Helm chart directory, run the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["install"]}," command using your configuration file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"helm install harmonize . \\\n  -f production.yaml \\\n  --namespace custody-core \\\n  --create-namespace\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify DNS and TLS: The output shows a success message. Verify that your DNS names and TLS certificates work by accessing the Web UI URL. The page should load, confirming your Ingress, DNS, and TLS configuration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test access:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Test DNS resolution\nnslookup custody.my-bank.com\n\n# Test TLS and web UI\ncurl -v https://custody.my-bank.com\n","lang":"bash"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-deploy-and-initialize-the-notary-genesis-call","__idx":5},"children":["Step 4: Deploy and initialize the notary (Genesis call)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that the API is running, you will deploy the notary, connect it to your HSM, and make the \"Genesis Call\" to initialize its master key."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure notary and HSM in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["harmonize.notary.protocol: grpc"]}," (recommended for production)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure the notary's KMS platform by setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components.notary.platform"]}," to one of the supported production values:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_luna"]}," - Thales Luna HSM (hardware HSM)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_blocksafe"]}," - BlockSafe HSM (hardware HSM)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_ibm"]}," - IBM HSM for deployments where the notary and/or vault are deployed on s390x architecture"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_aws"]}," - AWS CloudHSM (cloud HSM)"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fill in the required platform-specific section (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components.notary.kms_luna"]},") with your HSM's connection details. This enables and configures the \"KMS Connect\" sidecar container that manages the HSM connection."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"s390x support"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Starting in version 1.34, ","Ripple Custody (Vault)"," supports s390x (IBM) architecture for secure components only (the notary and vault). Non-secure components are not supported on s390x architecture."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example configuration for Luna HSM:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\nharmonize:\n  notary:\n    protocol: grpc  # Use grpc for production (better performance)\n\ncomponents:\n  notary:\n    platform: kms_luna\n    kms_luna:\n      host: \"hsm-notary.my-bank.local\"\n      port: \"1792\"\n      slot: \"1\"\n      pin: \"notary-hsm-pin-secret\"  # Use Kubernetes secrets for production\n      client:\n        certificate: |\n          -----BEGIN CERTIFICATE-----\n          ...\n          -----END CERTIFICATE-----\n        key: |\n          -----BEGIN PRIVATE KEY-----\n          ...\n          -----END PRIVATE KEY-----\n      server:\n        certificate: |\n          -----BEGIN CERTIFICATE-----\n          ...\n          -----END CERTIFICATE-----\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete configuration examples for all KMS platforms, see the platform-specific guides in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/how-to/integrate-kms/luna"},"children":["KMS Integration"]}," section."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upgrade the Deployment to deploy the notary bridge and notary pods:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"helm upgrade harmonize . \\\n  -f production.yaml \\\n  --namespace custody-core\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Monitor the notary pod. It will connect to the HSM, generate its key, and then wait for the Genesis Call."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Perform the Genesis API Request:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one-time, unauthenticated"]}," API operation. It initializes the entire system state (Root Domain, initial Users, and Policy setup). The notary generates and registers its master public key during this step."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Genesis API call:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://custody.my-bank.com/v1/genesis \\\n  -H \"Content-Type: application/json\" \\\n  -d @genesis-payload.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Simplified Genesis payload example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"rootDomainSetup\": {\n    \"id\": \"e7eb7b63-d63b-4c30-9cca-d3b1ea7e46ad\",\n    \"alias\": \"Root Domain\",\n    \"lock\": \"Unlocked\",\n    \"governingStrategy\": \"CoerceDescendants\",\n    \"permissions\": {\n      \"readAccess\": {\n        \"domains\": [\"operator\"],\n        \"users\": [\"operator\"],\n        \"accounts\": [\"operator\"],\n        \"transactions\": [\"operator\"]\n      }\n    },\n    \"users\": [\n      {\n        \"id\": \"e1fe3431-f899-427b-9e67-a75fb9fe5e57\",\n        \"alias\": \"admin@my-bank.com\",\n        \"publicKey\": \"MFkw...NfPfw/q9YW74Q==\",\n        \"roles\": [\"manager\"],\n        \"loginIds\": [\n          {\n            \"id\": \"admin@my-bank.com\",\n            \"providerId\": \"harmonize\"\n          }\n        ],\n        \"lock\": \"Unlocked\"\n      }\n    ],\n    \"policies\": [\n      {\n        \"id\": \"00000000-0000-0000-0000-000000000000\",\n        \"alias\": \"Catch-All Policy\",\n        \"rank\": 20,\n        \"workflow\": [\n          {\n            \"role\": \"manager\",\n            \"quorum\": 1,\n            \"type\": \"RoleQuorum\"\n          }\n        ]\n      }\n    ]\n  },\n  \"cryptoSetup\": {\n    \"apiSigning\": \"Secp256r1\",\n    \"collectionSigning\": \"Secp256r1\",\n    \"messageSigning\": \"Ed25519\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You can only run the Genesis operation once."]}," The system has an anti-rewind mechanism that blocks any attempt to rerun it. Plan your initial domain structure, users, and policies carefully."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed explanations of each Genesis payload section, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#genesis-payload-reference"},"children":["Genesis payload reference"]}," below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Upon successful execution (HTTP 200), the system initializes."]}," The response payload contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["notary public key"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notaryPublicKey"]},") - ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save this value, you will need it in Step 6"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["vault-trusted public key"]}," for messaging (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VAULT_TRUSTED_SIG"]},") - ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save this value, you will need it in Step 6"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-check-you-can-login","__idx":6},"children":["Step 5: Check you can login"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As an intermediary step, after initializing your instance via the Genesis, confirm that you can log in using the login details of one of the user profiles you configured in the Genesis."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-deploy-vault-and-ledgers","__idx":7},"children":["Step 6: Deploy vault and ledgers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this final step, you will deploy the vault and the blockchain indexers."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure vault in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},":"," ","The vault configuration is similar to that for the notary — you select a KMS platform and provide the connection details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key configuration sections:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set the vault KMS platform under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["harmonize.vaults.\"00000000-0000-0000-0000-000000000000\".platform"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure the platform-specific settings (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_luna"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_ibm"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kms_aws"]},", etc.)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Critical:"]}," Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["harmonize.vaults.\"00000000-0000-0000-0000-000000000000\".notary_public_key"]}," to the notary's public key you saved from the Genesis response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Vault configuration for Luna HSM:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\nharmonize:\n  vaults:\n    \"00000000-0000-0000-0000-000000000000\":  # Default vault UUID\n      enabled: true\n      platform: kms_luna\n      notary_public_key: \"ed25519:50692dfa472f013e2f87e5d210be40cefe178e33787be4688d5da0afe06ed149\"  # From Genesis response\n      kms_luna:\n        host: \"hsm-vault.my-bank.local\"\n        port: \"1792\"\n        slot: \"2\"\n        pin: \"vault-hsm-pin-secret\"  # Use Kubernetes secrets\n        client:\n          certificate: |\n            -----BEGIN CERTIFICATE-----\n            ...\n            -----END CERTIFICATE-----\n          key: |\n            -----BEGIN PRIVATE KEY-----\n            ...\n            -----END PRIVATE KEY-----\n        server:\n          certificate: |\n            -----BEGIN CERTIFICATE-----\n            ...\n            -----END CERTIFICATE-----\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete vault KMS configuration examples, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/how-to/integrate-kms/luna"},"children":["KMS integration"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure Ledgers (Blockchain Indexers) in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]},":"," ","Enable the blockchain networks you want to support. Each ledger requires connection to blockchain nodes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Blockchain Node Authentication:"]}," ","Depending on whether you're self-hosting nodes or using third-party providers, you may need to configure authentication:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Self-hosted nodes:"]}," May require basic authentication (username/password) or no authentication if on private network"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Third-party providers (Infura, Alchemy, QuickNode, etc.):"]}," Require API keys in the node URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Enterprise nodes:"]}," May require mTLS certificates or API tokens"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Ledger configuration:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# production.yaml\nharmonize:\n  ledgers:\n    bitcoin-mainnet:\n      enabled: true\n      node:\n        uri: \"https://bitcoin-node.my-bank.local:8332\"\n        # For basic auth: \"https://user:password@bitcoin-node.my-bank.local:8332\"\n    ethereum-mainnet:\n      enabled: true\n      node:\n        uri: \"https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY\"\n        # Or self-hosted: \"https://ethereum-node.my-bank.local:8545\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete ledger configuration including all supported networks and authentication methods, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/deployment/reference/indexers"},"children":["Ledgers Configuration Guide"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deploy vault and Indexers:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"helm upgrade harmonize . \\\n  -f production.yaml \\\n  --namespace custody-core\n\n# Deploy vault in separate namespace\nhelm upgrade harmonize-vault . \\\n  -f production.yaml \\\n  --namespace custody-vault \\\n  --create-namespace\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify vault and Indexer pods are running:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Check the core services and indexers\nkubectl get pods -n custody-core\n\n# Check the vault\nkubectl get pods -n custody-vault\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All pods should be in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Running"]}," state."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-7-register-the-vault","__idx":8},"children":["Step 7: Register the vault"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Critical:"]}," Before you can use the vault to create blockchain accounts, you must register it in ","Ripple Custody (Vault)",". This creates the vault entity in the governance system."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you open a new vault, set the key management system (KMS). Choose either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HSM"]}," (hardware-security module) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MPC"]}," (multi-party computation). This setting enables correct behavior and does not affect existing vaults. For more information about MPC key management, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/how-to/integrate-kms/mpc/overview"},"children":["Multi-party computation (MPC) overview"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"obtain-the-vault-public-key","__idx":9},"children":["Obtain the vault public key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To register the vault, you first need to obtain the public key."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Access the vault logs according to the method supported for your architecture:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"kubectl logs -n custody-vault <vault-pod-name> -c vault-core | grep \"pubKeySig\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Look for the generated public key:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"[INFO] [] [InitSvc]: Vault Core pubKeySig (der base64): MCowBQYDK2VwAyEA0rG1QbK6fGtkgsf7XXdbTFJVojK30tNEKrcjicKeVbI=\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Copy the base64-encoded public key (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MCowBQYDK2VwAyEA0rG1QbK6fGtkgsf7XXdbTFJVojK30tNEKrcjicKeVbI="]},")."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"register-the-vault","__idx":10},"children":["Register the vault"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Register the vault using either the UI or API:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Option A: Register via UI"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Administration > Vaults"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a vault"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter the vault details:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Vault ID:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["00000000-0000-0000-0000-000000000000"]}," (the default vault UUID from your configuration)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Alias:"]}," A friendly name (e.g., \"Production vault\")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["KMS Type:"]}," Select ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HSM"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MPC"]}," if using MPC)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Public Key:"]}," Paste the public key from step 1"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Submit for Approval"]}," and sign the operation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Option B: Register via API"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Submit an intent to create the vault entity:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://custody.my-bank.com/v1/intents \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"request\": {\n      \"author\": {\n        \"id\": \"<YOUR_USER_ID>\",\n        \"domainId\": \"<ROOT_DOMAIN_ID>\"\n      },\n      \"expiryAt\": \"2025-12-31T23:59:59Z\",\n      \"targetDomainId\": \"<ROOT_DOMAIN_ID>\",\n      \"id\": \"<NEW_INTENT_UUID>\",\n      \"payload\": {\n        \"id\": \"00000000-0000-0000-0000-000000000000\",\n        \"alias\": \"Production vault\",\n        \"parameters\": {\n          \"type\": \"HSM\"\n        },\n        \"publicKey\": \"MCowBQYDK2VwAyEA0rG1QbK6fGtkgsf7XXdbTFJVojK30tNEKrcjicKeVbI=\",\n        \"lock\": \"Unlocked\",\n        \"description\": \"Production vault for digital asset custody\",\n        \"customProperties\": {},\n        \"type\": \"v0_CreateVault\"\n      },\n      \"description\": \"Register production vault\",\n      \"type\": \"Propose\"\n    },\n    \"signature\": \"<YOUR_SIGNATURE>\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed instructions on vault registration, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/ui/environment/vault/register"},"children":["Register vaults (UI)"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/api/environment/vault/register"},"children":["Register vaults (API)"]},"."]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify that the vault registered successfully:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check in the UI under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Administration > Vaults"]}," - you should see your vault listed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Or query via API: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/vaults/00000000-0000-0000-0000-000000000000"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-8-verify-full-installation","__idx":11},"children":["Step 8: Verify full installation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At this point, your installation is complete. Verify the system is working by creating a test blockchain account:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log in to the Web UI using the credentials from your Genesis payload."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Accounts > Create Account"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a test account on one of your enabled blockchains (e.g., Bitcoin, Ethereum)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If this creates the account successfully and you can see the blockchain address, you have verified your installation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What this verifies:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Core services are running."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["notary connects and signs transactions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["vault has registered and operates correctly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Indexers connect to blockchain nodes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["End-to-end workflow (governance to vault to blockchain) is functional."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"genesis-payload-reference","__idx":12},"children":["Genesis payload reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section provides detailed explanations of each section in the Genesis API payload."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"complete-genesis-payload-example","__idx":13},"children":["Complete Genesis payload example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Complete genesis request body","header":{"title":"Complete genesis request body","controls":{"copy":{}}},"source":"{\n    \"rootDomainSetup\": {\n        \"id\": \"e7eb7b63-d63b-4c30-9cca-d3b1ea7e46ad\",\n        \"alias\": \"Root domain\",\n        \"lock\": \"Unlocked\",\n        \"governingStrategy\": \"CoerceDescendants\",\n        \"permissions\": {\n            \"readAccess\": {\n                \"domains\": [\"operator\"],\n                \"users\": [\"operator\"],\n                \"endpoints\": [\"operator\"],\n                \"policies\": [\"operator\"],\n                \"accounts\": [\"operator\"],\n                \"transactions\": [\"operator\"],\n                \"requests\": [\"operator\"],\n                \"events\": [\"operator\"]\n            }\n        },\n        \"description\": \"A genesis payload for the creation of the root domain\",\n        \"customProperties\": {},\n        \"users\": [\n            {\n                \"id\": \"e1fe3431-f899-427b-9e67-a75fb9fe5e57\",\n                \"alias\": \"operator@company.com\",\n                \"publicKey\": \"MFkw...NfPfw/q9YW74Q==\",\n                \"roles\": [\"manager\"],\n                \"loginIds\": [\n                    {\"id\": \"op1@company.com\", \"providerId\": \"harmonize\"},\n                    {\"id\": \"op1@company.com\", \"providerId\": \"azure-ad\"}\n                ],\n                \"lock\": \"Unlocked\",\n                \"description\": \"A manager user\",\n                \"customProperties\": {}\n            }\n        ],\n        \"policies\": [\n            {\n                \"id\": \"00000000-0000-0000-0000-000000000000\",\n                \"alias\": \"Catch-All Policy\",\n                \"rank\": 20,\n                \"intentTypes\": null,\n                \"scope\": \"Self\",\n                \"scriptingEngine\": \"Javascript_v0\",\n                \"condition\": {\n                    \"expression\": \"context.request.author.id == 'e1fe3431-f899-427b-9e67-a75fb9fe5e57'\",\n                    \"type\": \"Expression\"\n                },\n                \"workflow\": [\n                    {\"role\": \"manager\", \"quorum\": 1, \"type\": \"RoleQuorum\"}\n                ],\n                \"lock\": \"Unlocked\",\n                \"description\": \"Policy for exception handling\",\n                \"customProperties\": {}\n            }\n        ],\n        \"descendants\": []\n    },\n    \"cryptoSetup\": {\n        \"apiSigning\": \"Secp256r1\",\n        \"collectionSigning\": \"Secp256r1\",\n        \"messageSigning\": \"Ed25519\"\n    },\n    \"tickers\": [\n        {\n            \"id\": \"688b48e3-8ce1-4e01-b242-96f03ecb554a\",\n            \"ledgerId\": \"bitcoin-testnet\",\n            \"kind\": \"Native\",\n            \"name\": \"Bitcoin testnet\",\n            \"decimals\": 8,\n            \"symbol\": \"tBTC\",\n            \"ledgerDetails\": {\"properties\": {\"type\": \"Native\"}, \"type\": \"Bitcoin\"},\n            \"lock\": \"Unlocked\",\n            \"description\": null,\n            \"customProperties\": {}\n        }\n    ],\n    \"systemProperties\": [\n        {\n            \"value\": {\n                \"publicKey\": {\"value\": \"MFkw...HdVNyxTyl1plgAfh/Yg==\"}\n            },\n            \"type\": \"StateReviewAuthorityProperty\"\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"root-domain-setup","__idx":14},"children":["Root domain setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section is the only mandatory one. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rootDomainSetup"]}," section resembles a standard new domain creation payload. You specify the read permissions, users, and policies to create in the new ","Ripple Custody (Vault)"," instance."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/ui/environment/domain/create"},"children":["Create domains (UI)"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/api/environment/domain/create"},"children":["Create domains (API)"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"governing-strategy","__idx":15},"children":["Governing strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During domain creation, you choose between these governing strategies:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CoerceDescendants"]},": The domain ignores the policies of its subdomains."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ConsiderDescendants"]},": The domain considers the policies of its subdomains."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This field is optional. If you do not specify a governing strategy during domain creation, the domain defaults to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ConsiderDescendants"]}," strategy. Once created, you cannot change the governing strategy for the domain."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To execute a coercive intent within a locked domain, you must unlock the domain first."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"permissions","__idx":16},"children":["Permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This access management section specifies the user roles that can view different entity types in the domain."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"users","__idx":17},"children":["Users"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section is similar to a standard new user creation payload. Create enough users, with appropriate roles, to fulfill the defined policies."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Users follow these identifier guidelines:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Users within the same domain cannot have the same alias."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Users that have the same public key in different domains must have the same alias."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Example user with four roles and Azure AD SSO","header":{"title":"Example user with four roles and Azure AD SSO","controls":{"copy":{}}},"source":"\"users\": [\n    {\n        \"id\": \"e1fe3431-f899-427b-9e67-a75fb9fe5e57\",\n        \"alias\": \"operator@ripple.com\",\n        \"publicKey\": \"MFkw...NfPfw/q9YW74Q==\",\n        \"roles\": [\"manager\",\"compliance\",\"director\",\"operator\"],\n        \"loginIds\": [\n            {\"id\": \"op1@company.com\", \"providerId\": \"harmonize\"},\n            {\"id\": \"op1@company.com\", \"providerId\": \"azure-ad\"}\n        ],\n        \"lock\": \"Unlocked\",\n        \"description\": \"A user\",\n        \"customProperties\": {}\n    }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a detailed description of the user creation payload, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/ui/environment/user/create"},"children":["Create a user (UI)"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/api/environment/user/create"},"children":["Create a user (API)"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"policies","__idx":18},"children":["Policies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section is similar to a standard new policy creation payload. Include a breakglass policy. For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/get-started/design/policies/breakglass"},"children":["Breakglass policy"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a detailed description of the policy creation payload, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/get-started/design/policies"},"children":["Policies"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"descendants","__idx":19},"children":["Descendants"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section is optional. Specify subdomains as an array of domain objects inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["descendants"]}," property. For each subdomain, specify the same information as for the root domain."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"crypto-setup","__idx":20},"children":["Crypto setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This optional section specifies the cryptographic methods (elliptic curves) that the notary uses to create and verify signatures."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can specify different elliptic curves for different operations:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSigning"]},": The curve used to sign payloads returned to users following a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collectionSigning"]},": The curve for signing the roots of all collections' Merkle trees. This guarantees tamper-proof storage of the information. For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/concepts/security"},"children":["Security"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageSigning"]},": The curve used to sign internal messages from the notary to the vault."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For all types of operations you can choose between ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Secp256r1"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Secp256k1"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ed25519"]}," elliptic curves."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tickers","__idx":21},"children":["Tickers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This optional section includes a list of tickers and other assets available for blockchain ledgers. Use this section to provide a list of pre-validated tickers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"system-properties","__idx":22},"children":["System properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This optional section registers the public key of the state review authority. Use a public key in a standard ","Ripple Custody (Vault)"," accepted format (secp256k1, secp256r1, or Ed25519). Represent it as a Base64-encoded string."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The state review authority acts as a trusted party to confirm the authenticity of the system state if you need to recover the anti-rewind file (ARF)."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you do not specify this information during Genesis, register it as soon as possible afterwards. This allows you to recover your system in a disaster recovery scenario. For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/system-management/disaster-recovery"},"children":["Disaster recovery"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"genesis-events","__idx":23},"children":["Genesis events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you run the Genesis operation, ","Ripple Custody (Vault)"," includes two properties in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GenesisSucceeded"]}," event:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["genesis"]},": A data structure holding the notary-signed original Genesis payload."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdEntitiesReferences"]},": Key information on the data created."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.34/system-management/events#genesis-event"},"children":["Event management > Genesis event"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reference-productionyaml-vs-genesis-block","__idx":24},"children":["(Reference) production.yaml vs. Genesis block"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is critical to understand the difference between the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," file and the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Genesis block"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," file (Helm configuration):"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Purpose:"]}," Defines infrastructure-level settings (the \"plumbing\")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mutability:"]}," Mutable. You change this file to perform upgrades or update database passwords."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Controls:"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["How"]}," the app runs (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["database.host"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["replicaCount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ingress.host"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When used:"]}," On every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["helm install"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["helm upgrade"]},"."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The Genesis block (Governance configuration):"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Purpose:"]}," Defines immutable, application-level governance rules (the \"constitution\")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mutability:"]}," Immutable. The system loads it ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["once"]}," during the Genesis API call."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Controls:"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["What"]}," the app does (e.g., initial admin users, root domain, policies)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When used:"]}," Loaded ONCE during first-time initialization."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more details, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#genesis-payload-reference"},"children":["Genesis payload reference"]}," section above."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"post-install-configuring-secrets-injection","__idx":25},"children":["(Post-install) Configuring secrets injection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For your initial deployment, you likely used standard Kubernetes secrets to store passwords (e.g., db-password-secret). For a hardened production environment, move these secrets into a dedicated external secrets manager."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-kubernetes-secrets","__idx":26},"children":["Using Kubernetes Secrets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the default method, which you used during the initial installation."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How it works:"]}," You manually create a Kubernetes Opaque secret. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production.yaml"]}," file tells the application pods to mount this secret."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# 1. Create the secret\nkubectl create secret generic db-password-secret \\\n  -n custody-core \\\n  --from-literal=password='my-super-secret-db-password'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# 2. Configure production.yaml\npostgresql:\n  external:\n    existingSecret: \"db-password-secret\"\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Limitation:"]}," Kubernetes stores the secret (base64 encoded, not encrypted at rest by default)."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-an-external-secrets-manager-recommended","__idx":27},"children":["Using an external secrets manager (recommended)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This method uses a tool like the External Secrets Operator (ESO) to fetch secrets from an external vault (e.g., HashiCorp Vault, Conjur) and inject them into your application."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How it works:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prerequisites:"]}," You must have an external secrets manager and have the External Secrets Operator installed in your cluster."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configure production.yaml:"]}," You tell the chart ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["not"]}," to use existingSecret, but to instead get the secret from an external source."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"postgresql:\n  external:\n    # existingSecret: \"db-password-secret\"  # Disable this\n    externalSecret:\n      enabled: true  # Tells the chart to create an 'ExternalSecret' object\n      secretStoreName: \"hashicorp-vault-backend\" \\# \\<-- You must create this 'SecretStore' object  \n      remoteKey: \"ripple-custody/db-password\" \\# \\<-- Path to the secret in HashiCorp Vault  \n      remoteProperty: \"password\" \\# \\<-- Key inside that secret\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deploy: When you run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["helm upgrade"]},", the chart creates an ExternalSecret object. The ESO detects this, connects to your vault, and fetches the secret. It ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["then"]}," creates the final db-password-secret in Kubernetes for the application to use. This approach provides far more security because your hardened vault remains the \"source of truth\"."]}]}]}]}]}]},"headings":[{"value":"Installation and initialization","id":"installation-and-initialization","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Step 1: Verify prerequisites","id":"step-1-verify-prerequisites","depth":2},{"value":"Step 2: Initial production.yaml configuration","id":"step-2-initial-productionyaml-configuration","depth":2},{"value":"Step 3: Deploy the core services","id":"step-3-deploy-the-core-services","depth":2},{"value":"Step 4: Deploy and initialize the notary (Genesis call)","id":"step-4-deploy-and-initialize-the-notary-genesis-call","depth":2},{"value":"Step 5: Check you can login","id":"step-5-check-you-can-login","depth":2},{"value":"Step 6: Deploy vault and ledgers","id":"step-6-deploy-vault-and-ledgers","depth":2},{"value":"Step 7: Register the vault","id":"step-7-register-the-vault","depth":2},{"value":"Obtain the vault public key","id":"obtain-the-vault-public-key","depth":3},{"value":"Register the vault","id":"register-the-vault","depth":3},{"value":"Step 8: Verify full installation","id":"step-8-verify-full-installation","depth":2},{"value":"Genesis payload reference","id":"genesis-payload-reference","depth":2},{"value":"Complete Genesis payload example","id":"complete-genesis-payload-example","depth":3},{"value":"Root domain setup","id":"root-domain-setup","depth":3},{"value":"Governing strategy","id":"governing-strategy","depth":4},{"value":"Permissions","id":"permissions","depth":4},{"value":"Users","id":"users","depth":4},{"value":"Policies","id":"policies","depth":4},{"value":"Descendants","id":"descendants","depth":4},{"value":"Crypto setup","id":"crypto-setup","depth":3},{"value":"Tickers","id":"tickers","depth":3},{"value":"System properties","id":"system-properties","depth":3},{"value":"Genesis events","id":"genesis-events","depth":3},{"value":"(Reference) production.yaml vs. Genesis block","id":"reference-productionyaml-vs-genesis-block","depth":2},{"value":"(Post-install) Configuring secrets injection","id":"post-install-configuring-secrets-injection","depth":2},{"value":"Using Kubernetes Secrets","id":"using-kubernetes-secrets","depth":3},{"value":"Using an external secrets manager (recommended)","id":"using-an-external-secrets-manager-recommended","depth":3}],"frontmatter":{"seo":{"title":"Installation and initialization"}},"lastModified":"2026-06-26T11:15:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.34/deployment/install/installation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}