From 8ac2ab9c56c914e8caa9b394d6302af8ab35446d Mon Sep 17 00:00:00 2001 From: Simon Stone Date: Mon, 18 May 2020 14:30:11 +0100 Subject: [PATCH] Multiple tutorial updates (resolves #231, resolves #233) (#238) - Mention new common-vars.yml file - Fix shell extensions (#233) - Mention removing imported identities (#231) Signed-off-by: Simon Stone --- docs/source/tutorials/building.rst | 18 +++++++++++++----- docs/source/tutorials/joining.rst | 18 +++++++++++++----- 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/source/tutorials/building.rst b/docs/source/tutorials/building.rst index 965ab521..25f16caf 100644 --- a/docs/source/tutorials/building.rst +++ b/docs/source/tutorials/building.rst @@ -63,9 +63,15 @@ Edit the variable files `ordering-org-vars.yml` (for Ordering Org) and `org1-var 5. Set ``api_key`` to your API key or username. 6. Set ``api_secret`` to your API secret or password. -When the Ansible playbooks are run, the variable files are passed in to Ansible using the ``--extra-vars`` option, for example ``--extra-vars "@ordering-org-vars.yml"``. +There is also a common variables file, `common-vars.yml`. You do not need to edit this variable file. This file contains variables that are used by multiple organizations, for example the name of the channel that will be created, and the name of the smart contract that will be deployed. -Finally, all of these files contain a ``wait_timeout`` variable, with the default set to ``600`` (seconds). This is the amount of time in seconds to wait for certificate authorities, peers, and ordering services to start. Depending on your environment, you may need to increase this timeout, for example if it takes a long time to provision the persistent volumes for each component. +When the Ansible playbooks are run, the variable files are passed in to Ansible using the ``--extra-vars`` option, for example: + + :: + + ansible-playbook 01-create-ordering-organization-components.yml --extra-vars "@ordering-org-vars.yml" --extra-vars "@common-vars.yml" + +Finally, all of the organization specific variable files contain a ``wait_timeout`` variable, with the default set to ``600`` (seconds). This is the amount of time in seconds to wait for certificate authorities, peers, and ordering services to start. Depending on your environment, you may need to increase this timeout, for example if it takes a long time to provision the persistent volumes for each component. Building the network -------------------- @@ -88,7 +94,7 @@ If you have installed the collection using Ansible Galaxy, or from source, then :: - ./build_network -i build + ./build_network.sh -i build If you have installed the collection by building a Docker image, then run the script as follows: @@ -332,7 +338,7 @@ If you have installed the collection using Ansible Galaxy, or from source, then :: - ./build_network -i destroy + ./build_network.sh -i destroy If you have installed the collection by building a Docker image, then run the script as follows: @@ -348,4 +354,6 @@ If you have installed the collection by building a Docker image, then run the sc docker run --rm -v "$PWD:/tutorials" mydockerorg/ansible ansible-playbook /tutorials/build_network.sh -i destroy -After the script has finished, you should examine the output of the script to check that no errors have occurred whilst running the Ansible playbooks. After each Ansible playbook runs, Ansible outputs a ``PLAY RECAP`` section that details how many tasks have been executed, and how many of those tasks have failed. \ No newline at end of file +After the script has finished, you should examine the output of the script to check that no errors have occurred whilst running the Ansible playbooks. After each Ansible playbook runs, Ansible outputs a ``PLAY RECAP`` section that details how many tasks have been executed, and how many of those tasks have failed. + +Finally, if you have imported any identities into the IBM Blockchain Platform console wallet that have been created by these Ansible playbooks, then these identities will still remain in the wallet even after the network has been destroyed. Ansible cannot remove these identities from the wallet. You must remove these identities yourself using the IBM Blockchain Platform console. \ No newline at end of file diff --git a/docs/source/tutorials/joining.rst b/docs/source/tutorials/joining.rst index 4f7275ed..a502fd93 100644 --- a/docs/source/tutorials/joining.rst +++ b/docs/source/tutorials/joining.rst @@ -52,9 +52,15 @@ You must now edit the variable file for the new organization Org2, `org2-vars.ym 5. Set ``api_key`` to your API key or username. 6. Set ``api_secret`` to your API secret or password. -When the Ansible playbooks are run, the variable files are passed in to Ansible using the ``--extra-vars`` option, for example ``--extra-vars "@org2-vars.yml"``. +There is also a common variables file, `common-vars.yml`. You do not need to edit this variable file. This file contains variables that are used by multiple organizations, for example the name of the channel that will be created, and the name of the smart contract that will be deployed. -Finally, all of these files contain a ``wait_timeout`` variable, with the default set to ``600`` (seconds). This is the amount of time in seconds to wait for certificate authorities, peers, and ordering services to start. Depending on your environment, you may need to increase this timeout, for example if it takes a long time to provision the persistent volumes for each component. +When the Ansible playbooks are run, the variable files are passed in to Ansible using the ``--extra-vars`` option, for example: + + :: + + ansible-playbook 11-create-endorsing-organization-components.yml --extra-vars "@org2-vars.yml" --extra-vars "@common-vars.yml" + +Finally, all of the organization specific variable files contain a ``wait_timeout`` variable, with the default set to ``600`` (seconds). This is the amount of time in seconds to wait for certificate authorities, peers, and ordering services to start. Depending on your environment, you may need to increase this timeout, for example if it takes a long time to provision the persistent volumes for each component. Joining the network ------------------- @@ -77,7 +83,7 @@ If you have installed the collection using Ansible Galaxy, or from source, then :: - ./join_network -i join + ./join_network.sh -i join If you have installed the collection by building a Docker image, then run the script as follows: @@ -251,7 +257,7 @@ If you have installed the collection using Ansible Galaxy, or from source, then :: - ./join_network -i destroy + ./join_network.sh -i destroy If you have installed the collection by building a Docker image, then run the script as follows: @@ -267,4 +273,6 @@ If you have installed the collection by building a Docker image, then run the sc docker run --rm -v "$PWD:/tutorials" mydockerorg/ansible ansible-playbook /tutorials/join_network.sh -i destroy -After the script has finished, you should examine the output of the script to check that no errors have occurred whilst running the Ansible playbooks. After each Ansible playbook runs, Ansible outputs a ``PLAY RECAP`` section that details how many tasks have been executed, and how many of those tasks have failed. \ No newline at end of file +After the script has finished, you should examine the output of the script to check that no errors have occurred whilst running the Ansible playbooks. After each Ansible playbook runs, Ansible outputs a ``PLAY RECAP`` section that details how many tasks have been executed, and how many of those tasks have failed. + +Finally, if you have imported any identities into the IBM Blockchain Platform console wallet that have been created by these Ansible playbooks, then these identities will still remain in the wallet even after the network has been destroyed. Ansible cannot remove these identities from the wallet. You must remove these identities yourself using the IBM Blockchain Platform console. \ No newline at end of file