{"templateId":"markdown","versions":[{"version":"v1.40","label":"v1.40 STS","link":"/products/custody/deployment/install/first-time-installation","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/deployment/install/first-time-installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/deployment/install/first-time-installation","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/deployment/install/first-time-installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/deployment/install/first-time-installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/deployment/install/first-time-installation","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/deployment/install/first-time-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","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"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.38/deployment/install/helm-chart-installation"},"children":["Installation environment setup"]},".)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have access to ","Ripple Custody"," 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.38/deployment/install/helm-chart-installation"},"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":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/reference"},"children":[{"$$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 the one-time ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/genesis/payload-reference"},"children":["Genesis API call"]}," to initialize the first governed state and 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.38/deployment/install/helm-chart-installation"},"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. For configuration reference pages, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/reference"},"children":["Deployment reference"]},"."]},{"$$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: openid.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":"p","attributes":{},"children":["Before running this step, review ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/genesis"},"children":["Design your genesis governance model"]}," and assemble the payload with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/genesis/payload-reference"},"children":["Genesis payload reference"]},"."]},{"$$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"," 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.38/deployment/integrate-kms/on-premise-hsm/thales-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":["Use the finalized ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["genesis-payload.json"]}," from your ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/genesis"},"children":["genesis governance design"]},". For payload structure and examples, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/genesis/payload-reference"},"children":["Genesis payload reference"]},"."]},{"$$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":[{"$$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.38/deployment/integrate-kms/on-premise-hsm/thales-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":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Nodes requiring token-based auth (e.g., Besu nodes that issue short-lived JWTs):"]}," Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customJwt"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["header"]}," authentication mode in the UIS ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["indexer.node.authentication"]}," block. This automatically deploys a Node Gateway sidecar alongside the EVM indexer pod — no additional Helm flag is needed. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/overview/architecture/unified-indexer-service#node-authentication-for-evm-chains"},"children":["Node authentication for EVM chains"]}," for full configuration reference."]}]},{"$$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.38/deployment/reference/ledgers"},"children":["Ledgers configuration"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/reference/indexers"},"children":["Indexers configuration"]},"."]}]},{"$$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",". 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.38/deployment/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.38/identity-and-access/vault-management/manage-vaults#register-a-vault-in-the-ui"},"children":["Register a vault in the UI"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/identity-and-access/vault-management/manage-vaults#register-a-vault-with-the-api"},"children":["Register a vault with the 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":"reference-productionyaml-vs-genesis-block","__idx":12},"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":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/reference"},"children":[{"$$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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/genesis"},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/genesis/payload-reference"},"children":["Genesis payload reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"post-install-configuring-secrets-injection","__idx":13},"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":14},"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":15},"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":"(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-07-27T10:10:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.38/deployment/install/first-time-installation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}