R3 Docs R3 Docs Docs

Manual Bootstrapping

By default, the Corda installation process automatically performs various setup actions in Kafka and 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.

Kafka

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 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 to assist in the creation of the topics prior to Corda installation in one of two ways:

Topic Creation by Direct Connection

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.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.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. 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.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

Topic Creation by Scripting

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.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.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.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.

Database

By default, a Corda installation automatically creates and populates the database schema it requires. To create the schema manually, do the following:

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

    bootstrap:
  db:
    enabled: false

  2. Use the Corda CLI to generate DML files for creating the database schema. For example, the following command generates the files in the directory /tmp/db:

    corda-cli.sh database spec -c -l /tmp/db

    corda-cli.sh database spec -c -l /tmp/db

    corda-cli.cmd database spec -c -l /tmp/db

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

  4. 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> -p <RBAC-PASSWORD> \
  --name corda-rbac --jbdc-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.sh initial-config create-db-config -u <RBAC-USERNAME> -p <RBAC-PASSWORD> \
  --name corda-rbac --jbdc-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 --jbdc-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:

    config:
   encryption:
      salt: <SALT>
      passphrase: <PASSPHRASE>

    For example:

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

    corda-cli.sh initial-config create-db-config -u rbac-user -p rc9VLHU3 \
  --name corda-rbac --jbdc-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 rbac-user -p rc9VLHU3 `
  --name corda-rbac --jbdc-url jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=RBAC `
  --jdbc-pool-max-size 5 --salt X3UaCpUH --passphrase UUWLhD8S -l /tmp/db

  5. Review the DDL files generated and then execute against the database.

  6. 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 --jbdc-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.sh initial-config create-db-config -u <CRYPTO-USERNAME> -p <CRYPTO-PASSWORD> \
  --name corda-crypto --jbdc-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 --jbdc-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 crypto-user -p TqoCp4v2 \
  --name corda-crypto --jbdc-url jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=CRYPTO \
  --jdbc-pool-max-size 5 --salt X3UaCpUH --passphrase UUWLhD8S -l /tmp/db

    corda-cli.sh initial-config create-db-config -u crypto-user -p TqoCp4v2 \
  --name corda-crypto --jbdc-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 crypto-user -p TqoCp4v2 `
  --name corda-crypto --jbdc-url jdbc:postgresql://postgres.example.com:5432/cordacluster?currentSchema=CRYPTO `
  --jdbc-pool-max-size 5 --salt X3UaCpUH --passphrase UUWLhD8S -l /tmp/db

  7. Review the DDL files generated and then execute against the database.

  8. Execute the following Corda CLI command to generate DDL for populating the initial 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.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

  9. Review the DDL files generated and then execute against the database.

  10. 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>;

  11. 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.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.

  1. Review the DDL files generated and then execute against the database.

RBAC Roles

By default, a post-install job normally creates three default RBAC roles for the Corda API. To create the roles manually, do the following:

  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.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>
    <API-ENDPOINT> should be a URL where the Corda API is accessible, either via a load balancer or by forwarding port 8888 from one of the REST worker pods.

Previous
Deploying a Corda Cluster
Next
Operating

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