[FAB-17199] Add new test network tutorial #369
Conversation
docs/source/test_network.md
Outdated
| This command creates a Fabric network that consists of two peer nodes, one | ||
| ordering node, and an instance of the Fabric tools container. If the command | ||
| completes successfully, you script will print out the following logs of the nodes |
There was a problem hiding this comment.
This seems misplaced. You're in effect asking people to run a test network when they have no idea what it contains.
I get why --- people shouldn't have to dig around for the script command, but I would at least link to the "components of the network section" somewhere near the beginning so that first time readers can jump down and find out what's in the network they're deploying.
There was a problem hiding this comment.
I am going to leave as is. People have the notion of a blockchain network before they know what it does. The components overview is the directly section below, so I do not think that there needs to be a link.
docs/source/test_network.md
Outdated
| To ensure that transactions are trusted, transactions created using smart | ||
| contracts will need to be signed by multiple organizations to be added to the | ||
| channel ledger. Multiple signatures ensures that one organization has not | ||
| tampered with the ledger on their peer or used business logic that was not | ||
| agreed by the network. To sign a transaction, each organization needs to invoke | ||
| and execute the smart contract on their peer, which then signs the output of the | ||
| transaction. If the output is consistent and has been signed by enough | ||
| organizations, the transaction can be committed to the ledger. The policy that | ||
| specifies which set organizations on the channel need to execute the smart | ||
| contract is referred to as the endorsement policy, which is set for each | ||
| chaincode as part of the chaincode definition. | ||
|
|
There was a problem hiding this comment.
In general, I think it's a bit backwards to have so much in this paragraph and the one below about "how chaincodes work" rather than their conceptual purpose and role in the network (given comparably little space in the first paragraph). All of this stuff about signatures and executing chaincode on their peer is important, but needs to be understood in the context of smart contracts more in general.
Also worth noting again that we should have links to where some of this stuff is described elsewhere in more detail. I worry that these sections are sort of tweeners --- not going too deep but still trying to give people a good amount of information --- which are incredibly difficult to write. You might find these sections get a lot of scrutiny from maintainers.
There was a problem hiding this comment.
I think mentioning the endorsement policy is important, but it is possible that this section can be cut down. I am going to leave as is for the moment, see what scrutiny I get.
| ## Bring up the network with Certificate Authorities | ||
|
|
||
| Hyperledger Fabric uses public key infrastructure (PKI) to verify the actions of |
There was a problem hiding this comment.
These "bring up the network" sections are organized somewhat strangely to me, especially this one after the CLI section above. I might put all of these sections together, either before or after the CLI section, and have links at the top of the doc that can take people down to these "optional deployment" sections.
There was a problem hiding this comment.
I debated this in terms of putting it above the channel creation, but I wanted to create a friendly experience where users were not hit by too much information to quickly. I will put a link to this section from the top however.
nikhil550
force-pushed
the
FAB-17199
branch
2 times, most recently
from
8d97a2b
to
816a6a3
Compare
nikhil550
requested review from
ale-linux,
binhn,
C0rWin,
christo4ferris,
denyeart,
guoger,
jyellick,
kchristidis,
manish-sethi,
mastersingh24,
muralisrini,
sykesm and
yacovm
as code owners
docs/source/test_network.md
Outdated
|
|
||
| The sample network deploys a Fabric network with Docker Compose. Because the | ||
| nodes are isolated within a Docker Compose network, you cannot connect other | ||
| running Fabric nodes to the test network. |
There was a problem hiding this comment.
technically speaking, docker compose does not prohibit it, one could just expose host port and manually add hosts entries. I guess we could say some thing like:
extra configurations are needed to connect other running Fabric nodes, and is out of the scope of this tutorial
There was a problem hiding this comment.
I would rather be even stronger in terms of telling folks that this is not a prod deployment, and not to try to use it to connect to other nodes. How about this:
Because the nodes are isolated within a Docker Compose network, the test network is not configured to connect to other running fabric nodes.
nikhil550
force-pushed
the
FAB-17199
branch
2 times, most recently
from
982db8d
to
6f791d0
Compare
|
I don't see documentation for adding a new organization using addOrg3.sh script. What's the plan? |
We will rebase the adding an org to the network tutorial to the new test network and doc the addOrg3 script there. We will continue to use the byfn tutorial and eyfn until then. |
|
Long term the future of EYFN should be to focus on the process for creating the structure and crypto material for an org, and how to add the org to a channel through a channel update (what the json file and jq command would look like, in other words). We can leverage the updated Config Update doc -- https://hyperledger-fabric.readthedocs.io/en/master/config_update.html -- for the latter, rather than that being the focus of an Add an Org tutorial. |
Add new test network tutorial as part of gettign started section Signed-off-by: NIKHIL E GUPTA <negupta@us.ibm.com>
Signed-off-by: NIKHIL E GUPTA negupta@us.ibm.com
Add new test network tutorial as part of getting started section.
Type of change
Description
Users would be guided toward the new test network directly after they install the prerequisites and fabric docker images and samples. The tutorial is the first step toward replacing the build a network tutorial in the long term.
Related issues
The PR to add the test network to the Fabric samples:
hyperledger/fabric-samples#80. (Merged)
The tutorial should be merged after the sample