R3 Docs R3 Docs Home

Manual Bootstrapping heading-link-icon

By default, the Corda installation process automatically performs various setup actions in Kafka The means by which Corda workers communicate, acting as a central message bus between the worker processes. , the database, and for Corda RBAC. If you require additional control, you can disable these automatic setup processes and an administrator can manually perform the actions with the assistance of the Corda CLI.

This section describes how to configure the following:

When you have completed the manual configuration of the above, you can Deploy Corda.

By default, a Corda installation automatically creates the Kafka topics it requires. To create the topics manually, do the following:

  1. Set the following override in the deployment configuration to disable the automatic creation:

    bootstrap:
  kafka:
    enabled: false

  2. Create a Kafka client properties file. The following is an example properties file for a Kafka cluster using TLS Transport Layer Security. A protocol that establishes an encrypted session between two computers on the Internet. and SASL authentication:

    security.protocol=SASL_SSL
sasl.mechanism=SCRAM-SHA-256
sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required username="<USERNAME>" password="<PASSWORD>" ;
ssl.truststore.location=ca.crt
ssl.truststore.type=PEM

    The examples that follow assume that this file is called config.properties.

  3. Use the Corda CLI A command line tool that supports various Corda-related tasks, including Corda Package Installer (CPI) creation and Corda cluster management. to assist in the creation of the topics prior to Corda installation in one of two ways:

In the first option, the Corda CLI connects directly to the Kafka broker to create the topics. The Corda CLI command to create the topics looks as follows:

corda-cli.sh topic -b <BOOTSTRAP-SERVERS> -k config.properties \
  create -r <REPLICAS> -p <PARTITIONS> connect

corda-cli.cmd topic -b <BOOTSTRAP-SERVERS> -k config.properties create -r <REPLICAS> -p <PARTITIONS> connect

For example:

corda-cli.sh topic -b kafka-1.example.com -k config.properties create -r 3 -p 10 connect

corda-cli.cmd topic -b kafka-1.example.com -k config.properties create -r 3 -p 10 connect

If you are authenticating Kafka users, the Corda CLI can also create Access Control List (ACL) entries as appropriate for each Corda worker JVM processes that run in a cluster and perform a specific task. The processes required to form a cluster depend on the deployment topology. Workers increase or scale back their capacity depending on the number of available tasks. . Specify a set of name-value pairs giving the Kafka username that will be used for each Corda worker:

corda-cli.sh topic -b <BOOTSTRAP-SERVERS> -k config.properties \
  create -r <REPLICAS> -p <PARTITIONS> \
  -u crypto=<CRYPTO_USER> -u db=<DB_USER> -u flow=<FLOW_USER> -u membership=<MEMBERSHIP_USER> \
  -u p2pGateway=<P2P_GATEWAY_USER> -u p2pLinkManager=<P2P_LINK_MANAGER_USER> -u rest=<REST_USER> \
  connect

corda-cli.cmd topic -b <BOOTSTRAP-SERVERS> -k config.properties `
  create -r <REPLICAS> -p <PARTITIONS> `
  -u crypto=<CRYPTO_USER> -u db=<DB_USER> -u flow=<FLOW_USER> -u membership=<MEMBERSHIP_USER> `
  -u p2pGateway=<P2P_GATEWAY_USER> -u p2pLinkManager=<P2P_LINK_MANAGER_USER> -u rest=<REST_USER> `
  connect

Alternatively, the Corda CLI can generate a script which you should review before executing against the broker. The script makes use of the kafka-topic.sh script provided with a Kafka installation.

Run the following Corda CLI command to generate the script:

corda-cli.sh topic -b <BOOTSTRAP-SERVERS> -k config.properties \
  create -r <REPLICAS> -p <PARTITIONS> script -f <FILE> -c <CONCURRENCY>

corda-cli.cmd topic -b <BOOTSTRAP-SERVERS> -k config.properties create -r <REPLICAS> -p <PARTITIONS> script -f <FILE> -c <CONCURRENCY>

Where <FILE> is the name of the file in which to save the script and <CONCURRENCY> is the number of topics to create in parallel to speed execution.

For example:

corda-cli.sh topic -b kafka-1.example.com -k config.properties \
  create -r 3 -p 10 script -f create.sh -c 6

corda-cli.cmd topic -b kafka-1.example.com -k config.properties create -r 3 -p 10 script -f create.sh -c 6

If you are authenticating Kafka users, the Corda CLI can also create Access Control List (ACL) entries as appropriate for each Corda worker. Specify a set of name-value pairs giving the Kafka username that will be used for each Corda worker:

corda-cli.sh topic -b <BOOTSTRAP-SERVERS> -k config.properties \
  create -r <REPLICAS> -p <PARTITIONS> \
  -u crypto=<CRYPTO_USER> -u db=<DB_USER> -u flow=<FLOW_USER> -u membership=<MEMBERSHIP_USER> \
  -u p2pGateway=<P2P_GATEWAY_USER> -u p2pLinkManager=<P2P_LINK_MANAGER_USER> -u rest=<REST_USER> \
  connect

corda-cli.cmd topic -b <BOOTSTRAP-SERVERS> -k config.properties `
  create -r <REPLICAS> -p <PARTITIONS> `
  -u crypto=<CRYPTO_USER> -u db=<DB_USER> -u flow=<FLOW_USER> -u membership=<MEMBERSHIP_USER> `
  -u p2pGateway=<P2P_GATEWAY_USER> -u p2pLinkManager=<P2P_LINK_MANAGER_USER> -u rest=<REST_USER> `
  connect

You can then execute the create script to create the topics.

By default, a Corda installation automatically creates and populates the database schema it requires.

To create the schema manually, set the following override in the deployment configuration to disable the automatic creation:

bootstrap:
  db:
    enabled: false

Create and populate the database schema, as follows:

  1. Create the database tables.
  2. Populate the RBAC database connection configuration.
  3. Populate the crypto database connection configuration.
  4. Populate the virtual nodes database connection configuration.
  5. Populate the REST admin user.
  6. Create the RBAC and crypto users.
  7. Populate the crypto configuration.

  1. Use the Corda CLI to generate DML files for creating the database tables to use for each of the crypto, config, and rbac components.

    The following command specifies that the CONFIG, RBAC, and CRYPTO schema should be used for the corresponding components and generates the files in the directory /tmp/db:

    corda-cli.sh database spec -g config:CONFIG,rbac:RBAC,crypto:CRYPTO -c -l /tmp/db

    corda-cli.cmd database spec -g config:CONFIG,rbac:RBAC,crypto:CRYPTO -c -l /tmp/db

  2. Review the DML files generated and then execute against the database.

Depending on your installation, follow the steps in one of the following sections to generate DDL for populating the RBAC database connection configuration:

  1. Execute the following Corda CLI command to generate DDL for populating the RBAC Role-based access control. Also known as role-based security. A permission system to restrict system access based on assigned permissions. database connection configuration:

    corda-cli.sh initial-config create-db-config -u <RBAC-USERNAME> -p <RBAC-PASSWORD> \
  --name corda-rbac --jdbc-url 'jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=RBAC' \
  --jdbc-pool-max-size <POOL-SIZE> --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u <RBAC-USERNAME> -p <RBAC-PASSWORD> `
  --name corda-rbac --jdbc-url jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=RBAC `
  --jdbc-pool-max-size <POOL-SIZE> --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db

    The <SALT> and <PASSPHRASE> are used to encrypt the credentials in the database. These must match the values specified in the Corda deployment configuration.

    For example:

    corda-cli.sh initial-config create-db-config -u rbacuser -p rc9VLHU3 \
  --name corda-rbac --jdbc-url 'jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=RBAC' \
  --jdbc-pool-max-size 5 --salt X3UaCpUH --passphrase UUWLhD8S -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u rbacuser -p rc9VLHU3 `
   --name corda-rbac --jdbc-url jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=RBAC `
   --jdbc-pool-max-size 5 --salt X3UaCpUH --passphrase UUWLhD8S -l /tmp/db

  2. Review the DDL files generated and then execute against the database, ensuring that you apply them to the CONFIG schema.

  1. Execute the following Corda CLI command to generate DDL for populating the RBAC database connection configuration:

    corda-cli.sh initial-config create-db-config -u <RBAC-USERNAME> \
   --name corda-rbac --jdbc-url 'jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=RBAC' \
   --jdbc-pool-max-size <POOL-SIZE> -t VAULT --vault-path <path-to-corda-created-secrets> --key rbac -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u <RBAC-USERNAME> `
  --name corda-rbac --jdbc-url jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=RBAC `
  --jdbc-pool-max-size <POOL-SIZE> -t VAULT --vault-path <path-to-corda-created-secrets> --key rbac -l /tmp/db

    The Vault parameters are used to retrieve encrypted values from the external secrets service. These must match the values specified in the Corda deployment configuration.

    For example:

    corda-cli.sh initial-config create-db-config -u rbacuser \
   --name corda-rbac --jdbc-url 'jdbc:postgresql://prereqs-postgres:5432/cordacluster?currentSchema=RBAC' \
   --jdbc-pool-max-size 5 -t VAULT --vault-path dbsecrets --key rbac -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u rbacuser `
  --name corda-rbac --jdbc-url jdbc:postgresql://prereqs-postgres:5432/cordacluster?currentSchema=RBAC `
  --jdbc-pool-max-size 5 -t VAULT --vault-path dbsecrets --key rbac -l /tmp/db

  2. Review the DDL files generated and then execute against the database, ensuring that you apply them to the CONFIG schema.

Depending on your installation, follow the steps in one of the following sections to generate DDL for populating the RBAC database connection configuration:

  1. Execute the following Corda CLI command to generate DDL for populating the Crypto database connection configuration:

    corda-cli.sh initial-config create-db-config -u <CRYPTO-USERNAME> -p <CRYPTO-PASSWORD> \
  --name corda-crypto --jdbc-url `jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=CRYPTO` \
  --jdbc-pool-max-size <POOL-SIZE> --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u <CRYPTO-USERNAME> -p <CRYPTO-PASSWORD> `
  --name corda-crypto --jdbc-url jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=CRYPTO `
  --jdbc-pool-max-size <POOL-SIZE> --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db

    The <SALT> and <PASSPHRASE> must match those used above and specified in the Corda deployment configuration.

    For example:

    corda-cli.sh initial-config create-db-config -u cryptouser -p TqoCp4v2 \
  --name corda-crypto --jdbc-url 'jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=CRYPTO' \
  --jdbc-pool-max-size 5 --salt X3UaCpUH --passphrase UUWLhD8S -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u cryptouser -p TqoCp4v2 `
  --name corda-crypto --jdbc-url jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=CRYPTO `
  --jdbc-pool-max-size 5 --salt X3UaCpUH --passphrase UUWLhD8S -l /tmp/db

  2. Review the DDL files generated and then execute against the database, ensuring that you apply them to the CONFIG schema.

  1. Execute the following Corda CLI command to generate DDL for populating the Crypto database connection configuration:

    corda-cli.sh initial-config create-db-config -u <CRYPTO-USERNAME> \
  --name corda-crypto --jdbc-url `jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=CRYPTO` \
  --jdbc-pool-max-size <POOL-SIZE> -t VAULT --vault-path <path-to-corda-created-secrets> --key crypto -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u <CRYPTO-USERNAME> `
  --name corda-crypto --jdbc-url jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>?currentSchema=CRYPTO `
  --jdbc-pool-max-size <POOL-SIZE> -t VAULT --vault-path <path-to-corda-created-secrets> --key crypto -l /tmp/db

    The Vault parameters are used to retrieve encrypted values from the external secrets service. These must match the values specified in the Corda deployment configuration.

    For example:

    corda-cli.sh initial-config create-db-config -u cryptouser \
  --name corda-crypto --jdbc-url 'jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=CRYPTO' \
  --jdbc-pool-max-size 5 -t VAULT --vault-path dbsecrets --key crypto -l /tmp/db

    corda-cli.cmd initial-config create-db-config -u cryptouser `
  --name corda-crypto --jdbc-url jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=CRYPTO `
  --jdbc-pool-max-size 5 -t VAULT --vault-path dbsecrets --key crypto -l /tmp/db

  2. Review the DDL files generated and then execute against the database, ensuring that you apply them to the CONFIG schema.

Depending on your installation, follow the steps in one of the following sections to generate DDL for populating the RBAC database connection configuration:

  1. Execute the following Corda CLI command to generate DDL for populating the virtual nodes database connection configuration:

    corda-cli.sh initial-config create-db-config -u <VNODE-USERNAME> -p <VNODE-PASSWORD> \
  --name corda-virtual-nodes --jdbc-url 'jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>' \ 
  --jdbc-pool-max-size <POOL-SIZE> --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db \
  --is-admin

    corda-cli.cmd initial-config create-db-config -u <VNODE-USERNAME> -p <VNODE-PASSWORD> `
  --name corda-virtual-nodes --jdbc-url jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME> ` 
  --jdbc-pool-max-size <POOL-SIZE> --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db ` 
  --is-admin

  2. Review the DDL files generated and then execute against the database, ensuring that you apply them to the CONFIG schema.

  1. Execute the following Corda CLI command to generate DDL for populating the virtual nodes database connection configuration:

    corda-cli.sh initial-config create-db-config -u <VNODE-USERNAME> \
  --name corda-virtual-nodes --jdbc-url 'jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME>' \ 
  --jdbc-pool-max-size <POOL-SIZE> -t VAULT --vault-path <path-to-corda-created-secrets> --key vnodes -l /tmp/db \
  --is-admin

    corda-cli.cmd initial-config create-db-config -u <VNODE-USERNAME> `
  --name corda-virtual-nodes --jdbc-url jdbc:postgresql://<DB-HOST>:<DB-PORT>/<DB=NAME> ` 
  --jdbc-pool-max-size <POOL-SIZE> -t VAULT --vault-path <path-to-corda-created-secrets> --key vnodes -l /tmp/db `
  --is-admin

    For example:

    corda-cli.sh initial-config create-db-config -u <VNODE-USERNAME> \
  --name corda-virtual-nodes --jdbc-url 'jdbc:postgresql://prereqs-postgres:5432/cordacluster' \ 
  --jdbc-pool-max-size  5 -t VAULT --vault-path dbsecrets --key vnodes -l /tmp/db \
  --is-admin

    corda-cli.cmd initial-config create-db-config -u <VNODE-USERNAME> `
  --name corda-virtual-nodes --jdbc-url jdbc:postgresql://prereqs-postgres:5432/cordacluster ` 
  --jdbc-pool-max-size  5 -t VAULT --vault-path dbsecrets --key vnodes -l /tmp/db `
  --is-admin

  2. Review the DDL files generated and then execute against the database, ensuring that you apply them to the CONFIG schema.

  1. Execute the following Corda CLI command to generate DDL for populating the initial REST admin user for Corda:

    corda-cli.sh initial-config create-user-config -u <INITIAL-ADMIN-USERNAME> -p <INITIAL-ADMIN-PASSWORD> -l /tmp/db

    corda-cli.cmd initial-config create-user-config -u <INITIAL-ADMIN-USERNAME> -p <INITIAL-ADMIN-PASSWORD> -l /tmp/db

  2. Review the DDL files generated and then execute against the database, ensuring that you apply them to the RBAC schema.

The cluster database user is the user specified in db.cluster.username in the deployment configuration. Grant access to this user as follows:

GRANT USAGE ON SCHEMA CONFIG to <CLUSTER-DB-USER>;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA CONFIG to <CLUSTER-DB-USER>;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA CONFIG TO <CLUSTER-DB-USER>;

Create the RBAC and Crypto users and grant access as follows:

CREATE USER <RBAC-USERNAME> WITH ENCRYPTED PASSWORD '<RBAC-PASSWORD>';
GRANT USAGE ON SCHEMA RBAC to <RBAC-USERNAME>;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA RBAC to <RBAC-USERNAME>;
CREATE USER <CRYPTO-USERNAME> WITH ENCRYPTED PASSWORD '<CRYPTO-PASSWORD>';
GRANT USAGE ON SCHEMA CRYPTO to <CRYPTO-USERNAME>;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA CRYPTO to <CRYPTO-USERNAME>;

Depending on your installation, follow the steps in one of the following sections to generate DDL for populating the initial crypto configuration:

  1. Execute the following Corda CLI command to generate DDL for populating the initial crypto configuration:

    corda-cli.sh initial-config create-crypto-config --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db

    corda-cli.cmd initial-config create-crypto-config --salt <SALT> --passphrase <PASSPHRASE> -l /tmp/db

    The <SALT> and <PASSPHRASE> must match those used above and specified in the Corda deployment configuration.

  2. Review the DDL files generated and then execute against the database, ensuring that you apply to the CONFIG schema.

  1. Execute the following Corda CLI command to generate DDL for populating the initial crypto configuration:

    corda-cli.sh initial-config create-crypto-config -t VAULT -v cryptosecrets -ks salt -kp passphrase -l /tmp/db

    corda-cli.cmd initial-config create-crypto-config -t VAULT -v cryptosecrets -ks salt -kp passphrase -l /tmp/db

    salt and passphrase are the names of Vault keys and should be entered as shown: they are not to be substituted for any actual salt or passphrase.

  2. Review the DDL files generated and then execute against the database, ensuring that you apply to the CONFIG schema.

By default, a post-install job creates three default RBAC roles for the REST API. To create the roles manually, perform the steps described in this section.

  1. Set the following override in the deployment configuration to disable the automatic creation:

    bootstrap:
  rbac:
    enabled: false

  2. Execute the following three commands:

    corda-cli.sh initial-rbac user-admin --yield 300 --user <INITIAL-ADMIN-USERNAME> \
  --password <INITIAL-ADMIN-PASSWORD> --target <API-ENDPOINT>
corda-cli.sh initial-rbac vnode-creator --yield 300 --user <INITIAL-ADMIN-USERNAME> \
  --password <INITIAL-ADMIN-PASSWORD> --target <API-ENDPOINT>
corda-cli.sh initial-rbac corda-developer --yield 300 --user <INITIAL-ADMIN-USERNAME> \
  --password <INITIAL-ADMIN-PASSWORD> --target <API-ENDPOINT>

    corda-cli.cmd initial-rbac user-admin --yield 300 --user <INITIAL-ADMIN-USERNAME> `
  --password <INITIAL-ADMIN-PASSWORD> --target <API-ENDPOINT>
corda-cli.cmd initial-rbac vnode-creator --yield 300 --user <INITIAL-ADMIN-USERNAME> `
  --password <INITIAL-ADMIN-PASSWORD> --target <API-ENDPOINT>
corda-cli.cmd initial-rbac corda-developer --yield 300 --user <INITIAL-ADMIN-USERNAME> `
  --password <INITIAL-ADMIN-PASSWORD> --target <API-ENDPOINT>
Previous
Deploying
Next
Migrating to Corda Enterprise

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Chat with us
Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

Learn how

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Chat with us
Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Create a new issue
Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

Learn how