Skip to content

Commit 2557956

Browse files
nickgaskinickgaski
committed
TOC Proposal
This is a proposed re-architecture of the community documentation. IT IS NOT PERFECT. Do note that the majority of these new files are simply placeholders for in progress work. Questions to answer - does the flow/layout make sense? - are there missing topics? - are the topic headings intuitive? Disregard the formatting (e.g. inability to collapse sections, redundant headings, etc. That will be addressed in another patch set). [ci skip] Change-Id: Ic1ac43adc7c40c0be12355fedf35a42417716e26 Signed-off-by: Nick Gaski <[email protected]>
1 parent 22795e3 commit 2557956

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+1469
-519
lines changed

‎docs/FAQ/architecture_FAQ.md

+153
Large diffs are not rendered by default.

‎docs/Setup/NodeSDK-setup.md

100644100755
File mode changed.

‎docs/adminops.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Administration and operations
2+
3+
[WIP]
4+
...coming soon

‎docs/asset_cli.md

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
## Manually create and join peers to a new channel
2+
3+
Use the cli container to manually exercise the create channel and join channel APIs.
4+
5+
Channel - `myc1` already exists, so let's create a new channel named `myc2`.
6+
7+
Exec into the cli container:
8+
```bash
9+
docker exec -it cli bash
10+
```
11+
If successful, you should see the following in your terminal:
12+
```bash
13+
/opt/gopath/src/github.com/hyperledger/fabric/peer #
14+
```
15+
Send createChannel API to Ordering Service:
16+
```
17+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc2
18+
```
19+
This will return a genesis block - `myc2.block` - that you can issue join commands with.
20+
Next, send a joinChannel API to `peer0` and pass in the genesis block as an argument.
21+
The channel is defined within the genesis block:
22+
```
23+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer0:7051 peer channel join -b myc2.block
24+
```
25+
To join the other peers to the channel, simply reissue the above command with `peer1`
26+
or `peer2` specified. For example:
27+
```
28+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer1:7051 peer channel join -b myc2.block
29+
```
30+
Once the peers have all joined the channel, you are able to issues queries against
31+
any peer without having to deploy chaincode to each of them.
32+
33+
## Use cli to deploy, invoke and query
34+
35+
Run the deploy command. This command is deploying a chaincode named `mycc` to
36+
`peer0` on the Channel ID `myc2`. The constructor message is initializing `a` and
37+
`b` with values of 100 and 200 respectively.
38+
```
39+
CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode deploy -C myc2 -n mycc -p github.com/hyperledger/fabric/examples -c '{"Args":["init","a","100","b","200"]}'
40+
```
41+
Run the invoke command. This invocation is moving 10 units from `a` to `b`.
42+
```
43+
CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode invoke -C myc2 -n mycc -c '{"function":"invoke","Args":["move","a","b","10"]}'
44+
```
45+
Run the query command. The invocation transferred 10 units from `a` to `b`, therefore
46+
a query against `a` should return the value 90.
47+
```
48+
CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode query -C myc2 -n mycc -c '{"function":"invoke","Args":["query","a"]}'
49+
```
50+
You can issue an `exit` command at any time to exit the cli container.
51+
52+
## Creating your initial channel through the cli
53+
54+
If you want to manually create the initial channel through the cli container, you will
55+
need to edit the Docker Compose file. Use an editor to open `docker-compose-gettingstarted.yml` and
56+
comment out the `channel_test.sh` command in your cli image. Simply place a `#` to the left
57+
of the command. (Recall that this script is executing the create and join channel
58+
APIs when you run `docker-compose up`) For example:
59+
```bash
60+
cli:
61+
container_name: cli
62+
<CONTENT REMOVED FOR BREVITY>
63+
working_dir: /opt/gopath/src/github.com/hyperledger/fabric/peer
64+
# command: sh -c './channel_test.sh; sleep 1000'
65+
# command: /bin/sh
66+
```
67+
68+
Then use the cli commands from above.

‎docs/asset_sdk.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
## Use node SDK to register/enroll user, followed by deploy/invoke
2+
3+
The individual javascript programs will exercise the SDK APIs to register and enroll the client with
4+
the provisioned Certificate Authority. Once the client is properly authenticated,
5+
the programs will demonstrate basic chaincode functionalities - deploy, invoke, and query. Make
6+
sure you are in the working directory where you pulled the source code before proceeding.
7+
8+
Upon success of each node program, you will receive a "200" response in the terminal.
9+
10+
Register/enroll & deploy chaincode (Linux or OSX):
11+
```bash
12+
# Deploy initializes key value pairs of "a","100" & "b","200".
13+
GOPATH=$PWD node deploy.js
14+
```
15+
Register/enroll & deploy chaincode (Windows):
16+
```bash
17+
# Deploy initializes key value pairs of "a","100" & "b","200".
18+
SET GOPATH=%cd%
19+
node deploy.js
20+
```
21+
Issue an invoke. Move units 100 from "a" to "b":
22+
```bash
23+
node invoke.js
24+
```
25+
Query against key value "b":
26+
```bash
27+
# this should return a value of 300
28+
node query.js
29+
```
30+
Explore the various node.js programs, along with `example_cc.go` to better understand
31+
the SDK and APIs.

‎docs/asset_setup.md

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
## Prerequisites and setup
2+
3+
* [Go](https://golang.org/) - most recent version
4+
* [Docker](https://www.docker.com/products/overview) - v1.13 or higher
5+
* [Docker Compose](https://docs.docker.com/compose/overview/) - v1.8 or higher
6+
* [Node.js & npm](https://nodejs.org/en/download/) - node v6.9.5 and npm v3.10.10
7+
* [xcode](https://developer.apple.com/xcode/) - only required for OS X users
8+
* [nvm](https://github.com/creationix/nvm/blob/master/README.markdown) - if you want to use `nvm install` command
9+
If you already have node on your machine, use the node website to install v6.9.5 or
10+
issue the following command in your terminal:
11+
```bash
12+
nvm install v6.9.5
13+
```
14+
then execute the following to see your versions:
15+
```bash
16+
# should be 6.9.5
17+
node -v
18+
```
19+
AND
20+
```bash
21+
# should be 3.10.10
22+
npm -v
23+
```
24+
25+
## Curl the source code to create network entities
26+
27+
* Download the [cURL](https://curl.haxx.se/download.html) tool if not already installed.
28+
* Determine a location on your local machine where you want to place the Fabric artifacts and application code.
29+
```bash
30+
mkdir -p <my_dev_workspace>/hackfest
31+
cd <my_dev_workspace>/hackfest
32+
```
33+
Next, execute the following command:
34+
```bash
35+
curl -L https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sfhackfest/sfhackfest.tar.gz -o sfhackfest.tar.gz 2> /dev/null; tar -xvf sfhackfest.tar.gz
36+
```
37+
This command pulls and extracts all of the necessary artifacts to set up your
38+
network - Docker Compose script, channel generate/join script, crypto material
39+
for identity attestation, etc. In the `/src/github.com/example_cc` directory you
40+
will find the chaincode that will be deployed.
41+
42+
Your directory should contain the following:
43+
```bash
44+
JDoe-mbp: JohnDoe$ pwd
45+
/Users/JohnDoe
46+
JDoe-mbp: JohnDoe$ ls
47+
sfhackfest.tar.gz channel_test.sh src
48+
ccenv docker-compose-gettingstarted.yml tmp
49+
```
50+
51+
## Using Docker
52+
53+
You do not need to manually pull any images. The images for - `fabric-peer`,
54+
`fabric-orderer`, `fabric-ca`, and `cli` are specified in the .yml file and will
55+
automatically download, extract, and run when you execute the `docker-compose` command.
56+
57+
## Commands
58+
59+
The channel commands are:
60+
61+
* `create` - create and name a channel in the `orderer` and get back a genesis
62+
block for the channel. The genesis block is named in accordance with the channel name.
63+
* `join` - use the genesis block from the `create` command to issue a join
64+
request to a peer.
65+
66+
## Use Docker to spawn network entities & create/join a channel
67+
68+
Ensure the hyperledger/fabric-ccenv image is tagged as latest:
69+
```bash
70+
docker-compose -f docker-compose-gettingstarted.yml build
71+
```
72+
Create network entities, create channel, join peers to channel:
73+
```bash
74+
docker-compose -f docker-compose-gettingstarted.yml up -d
75+
```
76+
Behind the scenes this started six containers (3 peers, a "solo" orderer, cli and CA)
77+
in detached mode. A script - `channel_test.sh` - embedded within the
78+
`docker-compose-gettingstarted.yml` issued the create channel and join channel
79+
commands within the CLI container. In the end, you are left with a network and
80+
a channel containing three peers - peer0, peer1, peer2.
81+
82+
View your containers:
83+
```bash
84+
# if you have no other containers running, you will see six
85+
docker ps
86+
```
87+
Ensure the channel has been created and peers have successfully joined:
88+
```bash
89+
docker exec -it cli bash
90+
```
91+
You should see the following in your terminal:
92+
```bash
93+
/opt/gopath/src/github.com/hyperledger/fabric/peer #
94+
```
95+
To view results for channel creation/join:
96+
```bash
97+
more results.txt
98+
```
99+
You're looking for:
100+
```bash
101+
SUCCESSFUL CHANNEL CREATION
102+
SUCCESSFUL JOIN CHANNEL on PEER0
103+
SUCCESSFUL JOIN CHANNEL on PEER1
104+
SUCCESSFUL JOIN CHANNEL on PEER2
105+
```
106+
107+
To view genesis block:
108+
```bash
109+
more myc1.block
110+
```
111+
112+
Exit the cli container:
113+
```bash
114+
exit
115+
```
116+
117+
## Curl the application source code and SDK modules
118+
119+
* Prior to issuing the command, make sure you are in the same working directory
120+
where you curled the network code. AND make sure you have exited the cli container.
121+
* Execute the following command:
122+
```bash
123+
curl -OOOOOO https://raw.githubusercontent.com/hyperledger/fabric-sdk-node/v1.0-alpha/examples/balance-transfer/{config.json,deploy.js,helper.js,invoke.js,query.js,package.json}
124+
```
125+
126+
This command pulls the javascript code for issuing your deploy, invoke and query calls.
127+
It also retrieves dependencies for the node SDK modules.
128+
129+
* Install the node modules:
130+
```bash
131+
# You may be prompted for your root password at one or more times during this process.
132+
npm install
133+
```
134+
You now have all of the necessary prerequisites and Fabric artifacts.

‎docs/asset_trouble.md

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
## Troubleshooting
2+
3+
If you have existing containers running, you may receive an error indicating that a port is
4+
already occupied. If this occurs, you will need to kill the container that is using said port.
5+
6+
If a file cannot be located, make sure your curl commands executed successfully and make
7+
sure you are in the directory where you pulled the source code.
8+
9+
If you are receiving timeout or GRPC communication errors, make sure you have the
10+
correct version of Docker installed - v1.13.0. Then try restarting your failing
11+
docker process. For example:
12+
```bash
13+
docker stop peer0
14+
```
15+
Then:
16+
```bash
17+
docker start peer0
18+
```
19+
20+
Another approach to GRPC and DNS errors (peer failing to resolve with orderer and vice
21+
versa) is to hardcode the IP addresses for each. You will know if there is a DNS
22+
issue, because a `more results.txt` command within the cli container will display
23+
something similar to:
24+
```bash
25+
ERROR CREATING CHANNEL
26+
PEER0 ERROR JOINING CHANNEL
27+
```
28+
29+
Issue a `docker inspect <container_name>` to ascertain the IP address. For example:
30+
```bash
31+
docker inspect peer0 | grep IPAddress
32+
```
33+
AND
34+
```bash
35+
docker inspect orderer | grep IPAddress
36+
```
37+
Take these values and hard code them into your cli commands. For example:
38+
```bash
39+
CORE_PEER_COMMITTER_LEDGER_ORDERER=172.21.0.2:7050 peer channel create -c myc1
40+
```
41+
AND THEN
42+
```bash
43+
CORE_PEER_COMMITTER_LEDGER_ORDERER=<IP_ADDRESS> CORE_PEER_ADDRESS=<IP_ADDRESS> peer channel join -b myc1.block
44+
```
45+
46+
If you are seeing errors while using the node SDK, make sure you have the correct versions
47+
of node.js and npm installed on your machine. You want node v6.9.5 and npm v3.10.10.
48+
49+
If you ran through the automated channel create/join process (i.e. did not comment out
50+
`channel_test.sh` in the `docker-compose-gettingstarted.yml`), then channel - `myc1` - and
51+
genesis block - `myc1.block` - have already been created and exist on your machine.
52+
As a result, if you proceed to execute the manual steps in your cli container:
53+
```
54+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc1
55+
```
56+
Then you will run into an error similar to:
57+
```
58+
<EXACT_TIMESTAMP> UTC [msp] Sign -> DEBU 064 Sign: digest: 5ABA6805B3CDBAF16C6D0DCD6DC439F92793D55C82DB130206E35791BCF18E5F
59+
Error: Got unexpected status: BAD_REQUEST
60+
Usage:
61+
peer channel create [flags]
62+
```
63+
This occurs because you are attempting to create a channel named `myc1`, and this channel
64+
already exists! There are two options. Try issuing the peer channel create command
65+
with a different channel name - `myc2`. For example:
66+
```
67+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc2
68+
```
69+
Then join:
70+
```
71+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer0:7051 peer channel join -b myc2.block
72+
```
73+
74+
If you do choose to create a new channel, and want to run deploy/invoke/query with
75+
the node.js programs, you also need to edit the "channelID" parameter in the
76+
`config.json` file to match the new channel's name. For example:
77+
```
78+
{
79+
"chainName":"fabric-client1",
80+
"chaincodeID":"mycc",
81+
"channelID":"myc2",
82+
"goPath":"../../test/fixtures",
83+
"chaincodePath":"github.com/example_cc",
84+
```
85+
86+
OR, if you want your channel called - `myc1` -, remove your docker containers and
87+
then follow the same commands in the __Manually create and join peers to a new channel__
88+
topic.
89+
90+
## Clean up
91+
92+
Shut down your containers:
93+
```bash
94+
docker-compose -f docker-compose-gettingstarted.yml down
95+
```
96+
97+
## Helpful Docker tips
98+
99+
Remove a specific docker container:
100+
```bash
101+
docker rm <containerID>
102+
```
103+
Force removal:
104+
```bash
105+
docker rm -f <containerID>
106+
```
107+
Remove all docker containers:
108+
```bash
109+
docker rm -f $(docker ps -aq)
110+
```
111+
This will merely kill docker containers (i.e. stop the process). You will not lose any images.
112+
113+
Remove an image:
114+
```bash
115+
docker rmi <imageID>
116+
```
117+
Forcibly remove:
118+
```bash
119+
docker rmi -f <imageID>
120+
```
121+
Remove all images:
122+
```bash
123+
docker rmi -f $(docker images -q)
124+
```

‎docs/auction.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Art Auction
2+
3+
[WIP]
4+
...coming soon
5+
6+
Shows the provenance, attestation, and ownership of a piece of artwork and the
7+
ensuing interaction of the various stakeholders. Not yet stable with v1 codebase.
8+
9+
Learn more about the components [here](https://github.com/ITPeople-Blockchain/auction)
10+
11+
Learn more about the client-side application [here](https://github.com/ITPeople-Blockchain/auction-app)

‎docs/blockchain.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Why blockchain?
2+
3+
...coming soon

‎docs/bootstrap.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Starting a network
2+
3+
[WIP]
4+
...coming soon
5+
6+
Intended to contain the recommended steps for generating prerequisite cryptographic
7+
material and then bootstrapping an ordering service (i.e. overall network) with
8+
participating organizations, ordering node certificates, load balancing, configuration,
9+
policies, etc...

‎docs/capabilities.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## Capabilities
2+
3+
...coming soon
4+
5+
Identity Management, Privacy, Confidentiality, Throughput, Chaincode, Modularity

0 commit comments

Comments
 (0)