Skip to content

Commit 1325431

Browse files
nickgaskinickgaski
committed
getting started doc
TOC updated remove alpha remove CouchDB Remove editing of config.json remove vagrant change zip name to sfhackfest overview docker compose instructions manual instructions sdk explanation node.js programs new flow [ci skip] Change-Id: Id6c0df6401c810398931e2ef49b5524ab96243a6 Signed-off-by: Nick Gaski <[email protected]>
1 parent 8cbe594 commit 1325431

File tree

2 files changed

+256
-1
lines changed

2 files changed

+256
-1
lines changed

‎docs/gettingstarted.md

+255
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# Getting Started with v1.0 Hyperledger Fabric - App Developers
2+
This document demonstrates an example using the Hyperledger Fabric V1.0 architecture.
3+
The scenario will include the creation and joining of channels, client side authentication,
4+
and the deployment and invocation of chaincode. CLI will be used for the creation and
5+
joining of the channel and the node SDK will be used for the client authentication,
6+
and chaincode functions utilizing the channel.
7+
8+
Docker-compose will be used to create a consortium of three organizations, each
9+
running an endorsing/committing peer, as well as a "solo" orderer and a Certificate Authority (CA).
10+
The cryptographic material, based on standard PKI implementation, has been pre-generated
11+
and is included in the sfhackfest.tar.gz in order to expedite the flow. The CA, responsible for
12+
issuing, revoking and maintaining the crypto material represents one of the organizations and
13+
is needed by the client (node SDK) for authentication. In an enterprise scenario, each
14+
organization might have their own CA, with more complex security measures implemented - e.g.
15+
cross-signing certificates, etc.
16+
17+
The network will be generated automatically upon execution of `docker-compose up`,
18+
and the APIs for create channel and join channel will be explained and demonstrated;
19+
as such, a user can go through the steps to manually generate their own network
20+
and channel, or quickly jump to the application development phase.
21+
22+
## Prerequisites and setup
23+
24+
* [Docker](https://www.docker.com/products/overview) - v1.12 or higher
25+
* [Docker Compose](https://docs.docker.com/compose/overview/) - v1.8 or higher
26+
* [Node.js](https://nodejs.org/en/download/) - comes with the node package manager (npm).
27+
If you already have npm on your machine, issue the following command to retrieve the latest package:
28+
```bash
29+
npm install npm@latest
30+
```
31+
then execute the following to see your version:
32+
```bash
33+
npm -v
34+
```
35+
You're looking for a version higher than 2.1.8.
36+
37+
## Curl the source code to create network entities
38+
39+
* Download the [cURL](https://curl.haxx.se/download.html) tool if not already installed.
40+
* Determine a location on your local machine where you want to place the Fabric and application source.
41+
```bash
42+
mkdir -p <my_dev_workspace>/hackfest
43+
cd <my_dev_workspace>/hackfest
44+
```
45+
Next, execute the following command:
46+
```bash
47+
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
48+
```
49+
This command pulls and extracts all of the necessary artifacts to set up your network - docker compose script,
50+
channel generate/join script, crypto material for identity attestation, etc. In the /src/github.com/example_cc directory you
51+
will find the chaincode that will be deployed.
52+
53+
Your directory should contain the following:
54+
```bash
55+
JDoe-mbp: JohnDoe$ pwd
56+
/Users/JohnDoe
57+
JDoe-mbp: JohnDoe$ ls
58+
sfhackfest.tar.gz channel_test.sh src
59+
ccenv docker-compose-gettingstarted.yml tmp
60+
```
61+
62+
## Using Docker
63+
64+
You do not need to manually pull any images. The images for - `fabric-peer`,
65+
`fabric-orderer`, `fabric-ca`, and `cli` are specified in the .yml file and will
66+
automatically download, extract, and run when you execute the `docker-compose` commands.
67+
68+
## Commands
69+
70+
The channel commands are:
71+
* `create` - create and name a channel in the `orderer` and get back a genesis
72+
block for the channel. The genesis block is named in accordance with the channel name.
73+
* `join` - use the genesis block from the `create` command to issue a join request to a Peer.
74+
75+
## Use Docker to spawn network entities & create/join a channel
76+
77+
Ensure the hyperledger/fabric-ccenv image is tagged as latest:
78+
```bash
79+
docker-compose -f docker-compose-gettingstarted.yml build
80+
```
81+
Create network entities, create channel, join peers to channel:
82+
```bash
83+
docker-compose -f docker-compose-gettingstarted.yml up -d
84+
```
85+
Behind the scenes this started six containers (3 peers, "solo" orderer, CLI and CA)
86+
in detached mode. A script - channel_test.sh - embedded within the
87+
docker-compose-gettingstarted.yml issued the create channel and join channel commands within the
88+
CLI container. In the end, you are left with a network and a channel containing three
89+
peers - peer0, peer1, peer2.
90+
91+
View your containers:
92+
```bash
93+
# if you have no other containers running, you will see nine
94+
docker ps
95+
```
96+
97+
Ensure the channel has been created and peers have successfully joined:
98+
```bash
99+
docker exec -it cli sh
100+
```
101+
You should see the following in your terminal:
102+
```bash
103+
/opt/gopath/src/github.com/hyperledger/fabric/peer #
104+
```
105+
To view results for channel creation/join:
106+
```bash
107+
vi results.txt
108+
```
109+
To view logs:
110+
```bash
111+
vi log.txt
112+
```
113+
To view genesis block details:
114+
```bash
115+
vi myc1.block
116+
```
117+
118+
## Curl the application source code and SDK modules
119+
120+
* Prior to issuing the command, make sure you are in the same working directory where you curled the network code.
121+
* Execute the following command:
122+
```bash
123+
curl -OOOOOO https://raw.githubusercontent.com/hyperledger/fabric-sdk-node/master/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. It also
127+
retrieves dependencies for the node SDK modules.
128+
129+
* Install the node modules:
130+
```bash
131+
npm install
132+
```
133+
You may be prompted for your root password at one or more times during the `npm install`.
134+
At this point you have installed all of the prerequisites and source code.
135+
136+
## Use node SDK to register/enroll user and deploy/invoke/query
137+
138+
The individual javascript programs will exercise the SDK APIs to register and enroll the client with
139+
the provisioned Certificate Authority. Once the client is properly authenticated,
140+
the programs will demonstrate basic chaincode functionalities - deploy, invoke, and query. Make
141+
sure you are in the working directory where you pulled the source code. You can explore the individual
142+
javascript programs to better understand the various APIs.
143+
144+
Register and enroll the user & deploy chaincode:
145+
```bash
146+
GOPATH=$PWD node deploy.js
147+
```
148+
_if running on Windows_:
149+
```bash
150+
SET GOPATH=%cd%
151+
node deploy.js
152+
```
153+
Issue an invoke. Move units from "a" to "b":
154+
```bash
155+
node invoke.js
156+
```
157+
Query against key value "a":
158+
```bash
159+
node query.js
160+
```
161+
You will receive a "200 response" in your terminal if each command is successful.
162+
163+
## Manually create and join channel (optional)
164+
165+
To manually exercise the createChannel and joinChannel APIs through the CLI container, you will
166+
need to edit the Docker Compose file. Use an editor to open docker-compose-gettingstarted.yml and
167+
comment out the `channel_test.sh` command in your cli image. Simply place a `#` to the left
168+
of the command. For example:
169+
```bash
170+
cli:
171+
container_name: cli
172+
<CONTENT REMOVED FOR BREVITY>
173+
working_dir: /opt/gopath/src/github.com/hyperledger/fabric/peer
174+
# command: sh -c './channel_test.sh; sleep 1000'
175+
# command: /bin/sh
176+
```
177+
Exec into the cli container:
178+
```bash
179+
docker exec -it cli sh
180+
```
181+
If successful, you should see the following in your terminal:
182+
```bash
183+
/opt/gopath/src/github.com/hyperledger/fabric/peer #
184+
```
185+
Send createChannel API to Ordering Service:
186+
```
187+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc1
188+
```
189+
This will return a genesis block - myc1.block - that you can issue join commands with.
190+
Next, send a joinChannel API to peer0 and pass in the genesis block as an argument.
191+
The channel is defined within the genesis block:
192+
```
193+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer0:7051 peer channel join -b myc1.block
194+
```
195+
To join the other peers to the channel, simply reissue the above command with peer1
196+
or peer2 specified. For example:
197+
```
198+
CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer1:7051 peer channel join -b myc1.block
199+
```
200+
Once the peers have all joined the channel, you are able to issues queries against
201+
any peer without having to deploy chaincode to each of them.
202+
203+
## Use cli to deploy, invoke and query (optional)
204+
205+
Run the deploy command. This command is deploying a chaincode named `mycc` to
206+
`peer0` on the Channel ID `myc1`. The constructor message is initializing `a` and
207+
`b` with values of 100 and 200 respectively.
208+
```
209+
CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode deploy -C myc1 -n mycc -p github.com/hyperledger/fabric/examples -c '{"Args":["init","a","100","b","200"]}'
210+
```
211+
Run the invoke command. This invocation is moving 10 units from `a` to `b`.
212+
```
213+
CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode invoke -C myc1 -n mycc -c '{"function":"invoke","Args":["move","a","b","10"]}'
214+
```
215+
Run the query command. The invocation transferred 10 units from `a` to `b`, therefore
216+
a query against `a` should return the value 90.
217+
```
218+
CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode query -C myc1 -n mycc -c '{"function":"invoke","Args":["query","a"]}'
219+
```
220+
You can issue an `exit` command at any time to exit the cli container.
221+
222+
## Troubleshooting (optional)
223+
224+
If you have existing containers running you may receive an error indicating that a port is
225+
already occupied. If this occurs, you will need to kill the container that is using said port.
226+
227+
If a file cannot be located, make sure your curl commands executed successfully and make
228+
sure you are in the directory where you pulled the source code.
229+
230+
Remove a specific docker container:
231+
```bash
232+
docker rm <containerID>
233+
```
234+
Force removal:
235+
```bash
236+
docker rm -f <containerID>
237+
```
238+
Remove all docker containers:
239+
```bash
240+
docker rm -f $(docker ps -aq)
241+
```
242+
This will merely kill docker containers (i.e. stop the process). You will not lose any images.
243+
244+
Remove an image:
245+
```bash
246+
docker rmi <imageID>
247+
```
248+
Forcibly remove:
249+
```bash
250+
docker rmi -f <imageID>
251+
```
252+
Remove all images:
253+
```bash
254+
docker rmi -f $(docker images -q)
255+
```

‎mkdocs.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ pages:
1212
- Fabric overview: overview.md
1313
#- Fabric capabilities: capabilities.md
1414
#- Fabric architecture: architecture.md
15-
#- Getting started: getstarted.md
15+
- Getting started: gettingstarted.md
1616
#- Chaincode and sample program: chaincode.md
1717
- Glossary: glossary.md
1818

0 commit comments

Comments
 (0)