Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Deployment Documentation #4003

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

mbwhite
Copy link
Member

@mbwhite mbwhite commented Feb 7, 2023

Aim is to add in more information about deployments.To do this the section on production deployments has been refactored to make it easier to add information.

Not all the additional Information has been added in this commit.

Signed-off-by: Matthew B White whitemat@uk.ibm.com

Type of change

  • Bug fix
  • New feature
  • Improvement (improvement to code, performance, etc)
  • Test update
  • Documentation update

Description

Additional details

Related issues

Aim is to add in more information about deployments.To do this the section on production deployments
has been refactored to make it easier to add information.

Not all the additional Information has been added in this commit.

Signed-off-by: Matthew B White <whitemat@uk.ibm.com>
Copy link
Contributor

@denyeart denyeart left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the direction you are going. Having smaller modular topics is certainly better than one very long topic, and I like your split of Designing vs Deploying.
I've highlighted a few fundamental issues in this PR that we need to resolve before moving on to detailed content review.

@@ -1,217 +1,30 @@
Deploying a production network
==============================
Designing and Deploying a production network
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This becomes the name in the table of contents, we try to keep them shorter in table of contents.
But I understand what you are trying to do and we could therefore accept a longer name if you don't have an alternate idea.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a bit long I agree; could split into two complete sections.


.. _dg-step-one-decide-on-your-network-configuration:
If you are a smart contract or application developer, you should not need this level of expertise in deploying a production level Fabric network. However, you do need to be aware of how networks are deployed in order to develop effective smart contracts and applications. For a development environment to test chaincode, smart contracts, and applications check against, check out :doc:`Getting Started - Run Fabric`. These development environments do not cover issues such as security, resource management, and high availability. These issues become a priority when operating in production.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The links in this PR have largely broken, e.g. :doc:Getting Started - Run Fabric

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes - reading up RFT links :-)

------------------------------------------
:maxdepth: 2
:glob:
:caption: Designing
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like what you are doing with the table of contents within the topic, but we have lost the table of contents in the left-hand side.

Note that peer and orderer also have "planning", "checklist", and "deploy" topics similar to CA, but these topics are not present in the new contents.
To see what I mean, look at old table of contents here:
https://hyperledger-fabric.readthedocs.io/en/latest/deployment_guide_overview.html#creating-a-peer

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree - that's not right. Not found a good reference explaining how those TOCs are created

Fabric Network Deployment Considerations
========================================

The structure of a blockchain network will be dictated by the use case it's serving. Use the topics below to help explorer the issues that your use case has.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The items below are not "topics" that can be linked/explored :-)

@@ -0,0 +1,20 @@
Bare Metal Fabric Deployment
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The content below is not strictly about "Bare Metal Fabric Deployment". In fact there is more kubernetes considerations below than bare metal considerations!

@denyeart
Copy link
Contributor

denyeart commented Feb 7, 2023

By the way, did you know that you can click the Details link in the checks section to see the rendered content?
Look at the check for
"docs/readthedocs.org:hyperledger-fabric — Read the Docs build succeeded!"

@mbwhite
Copy link
Member Author

mbwhite commented Feb 8, 2023

@denyeart thanks for the review and the support of the direction; yes there is much to done.

I didn't know that about following the link very useful - I was building it locally to check (that is also very easy!)

Ordering nodes can be bootstrapped with a configuration block for an administrative channel known as the “system channel” (from which application channels can be created), or simply started and joined to application channels as needed. The recommended method is to bootstrap without a configuration block, which is the approach this deployment guide assumes you will take. For more information about creating a system channel genesis block and bootstrapping an ordering node with it, check out `Deploying a production network <https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployment_guide_overview.html#creating-an-ordering-node>`_ from the Fabric v2.2 documentation.

* **Channels and private data.**
Some networks might decide that :doc:`channels` are the best way to ensure privacy and isolation for certain transactions. Others might decide that fewer channels, supplemented where necessary with :doc:`private-data/private-data` collections, better serves their privacy needs.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better add:
And the private data can be utilized in combination with the channel, to achieve more flexible privacy protection.


* **Addresses and paths**: because peers are not entities unto themselves but interact with other peers and components, you must specify a series of addresses in the configuration. These include addresses where the peer itself can be found by other components as well as the addresses where, for example, chaincodes can be found (if you are employing external chaincodes). Similarly, you will need to specify the location of your ledger (as well as your state database type) and the path to your external builders (again, if you intend to employ external chaincodes). These include **Operations and metrics**, which allow you to set up methods for monitoring the health and performance of your peer through the configuration of endpoints.

* **Gossip**: components in Fabric networks communicate with each other using the "gossip" protocol. Through this protocol, they can be discovered by the discovery service and disseminate blocks and private data to each other. Note that gossip communications are secured using TLS.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gossip communications are secured using TLS -->
gossip communications can be secured using TLS.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants