1grpc Examples
2==============================================
3
4The examples require grpc-java to already be built. You are strongly encouraged
5to check out a git release tag, since there will already be a build of grpc
6available. Otherwise you must follow [COMPILING](../COMPILING.md).
7
8You may want to read through the
9[Quick Start Guide](https://grpc.io/docs/quickstart/java.html)
10before trying out the examples.
11
12To build the examples, run in this directory:
13
14```
15$ ./gradlew installDist
16```
17
18This creates the scripts `hello-world-server`, `hello-world-client`,
19`hello-world-tls-server`, `hello-world-tls-client`,
20`route-guide-server`, and `route-guide-client` in the
21`build/install/examples/bin/` directory that run the examples. Each
22example requires the server to be running before starting the client.
23
24For example, to try the hello world example first run:
25
26```
27$ ./build/install/examples/bin/hello-world-server
28```
29
30And in a different terminal window run:
31
32```
33$ ./build/install/examples/bin/hello-world-client
34```
35
36### Hello World with TLS
37
38Running the hello world with TLS is the same as the normal hello world, but takes additional args:
39
40**hello-world-tls-server**:
41
42```text
43USAGE: HelloWorldServerTls host port certChainFilePath privateKeyFilePath [trustCertCollectionFilePath]
44  Note: You only need to supply trustCertCollectionFilePath if you want to enable Mutual TLS.
45```
46
47**hello-world-tls-client**:
48
49```text
50USAGE: HelloWorldClientTls host port [trustCertCollectionFilePath] [clientCertChainFilePath] [clientPrivateKeyFilePath]
51  Note: clientCertChainFilePath and clientPrivateKeyFilePath are only needed if mutual auth is desired. And if you specify clientCertChainFilePath you must also specify clientPrivateKeyFilePath
52```
53
54#### Generating self-signed certificates for use with grpc
55
56You can use the following script to generate self-signed certificates for grpc-java including the hello world with TLS examples:
57
58```bash
59# Changes these CN's to match your hosts in your environment if needed.
60SERVER_CN=localhost
61CLIENT_CN=localhost # Used when doing mutual TLS
62
63echo Generate CA key:
64openssl genrsa -passout pass:1111 -des3 -out ca.key 4096
65echo Generate CA certificate:
66# Generates ca.crt which is the trustCertCollectionFile
67openssl req -passin pass:1111 -new -x509 -days 365 -key ca.key -out ca.crt -subj "/CN=${SERVER_CN}"
68echo Generate server key:
69openssl genrsa -passout pass:1111 -des3 -out server.key 4096
70echo Generate server signing request:
71openssl req -passin pass:1111 -new -key server.key -out server.csr -subj "/CN=${SERVER_CN}"
72echo Self-signed server certificate:
73# Generates server.crt which is the certChainFile for the server
74openssl x509 -req -passin pass:1111 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt
75echo Remove passphrase from server key:
76openssl rsa -passin pass:1111 -in server.key -out server.key
77echo Generate client key
78openssl genrsa -passout pass:1111 -des3 -out client.key 4096
79echo Generate client signing request:
80openssl req -passin pass:1111 -new -key client.key -out client.csr -subj "/CN=${CLIENT_CN}"
81echo Self-signed client certificate:
82# Generates client.crt which is the clientCertChainFile for the client (need for mutual TLS only)
83openssl x509 -passin pass:1111 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt
84echo Remove passphrase from client key:
85openssl rsa -passin pass:1111 -in client.key -out client.key
86echo Converting the private keys to X.509:
87# Generates client.pem which is the clientPrivateKeyFile for the Client (needed for mutual TLS only)
88openssl pkcs8 -topk8 -nocrypt -in client.key -out client.pem
89# Generates server.pem which is the privateKeyFile for the Server
90openssl pkcs8 -topk8 -nocrypt -in server.key -out server.pem
91```
92
93#### Hello world example with TLS (no mutual auth):
94
95```bash
96# Server
97./build/install/examples/bin/hello-world-server-tls mate 50440 ~/Downloads/sslcert/server.crt ~/Downloads/sslcert/server.pem
98# Client
99./build/install/examples/bin/hello-world-client-tls mate 50440 ~/Downloads/sslcert/ca.crt
100```
101
102#### Hello world example with TLS with mutual auth:
103
104```bash
105# Server
106./build/install/examples/bin/hello-world-server-tls mate 54440 ~/Downloads/sslcert/server.crt ~/Downloads/sslcert/server.pem ~/Downloads/sslcert/ca.crt
107# Client
108./build/install/examples/bin/hello-world-client-tls mate 54440 ~/Downloads/sslcert/ca.crt ~/Downloads/sslcert/client.crt ~/Downloads/sslcert/client.pem
109```
110
111That's it!
112
113Please refer to gRPC Java's [README](../README.md) and
114[tutorial](https://grpc.io/docs/tutorials/basic/java.html) for more
115information.
116
117## Maven
118
119If you prefer to use Maven:
120```
121$ mvn verify
122$ # Run the server
123$ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldServer
124$ # In another terminal run the client
125$ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldClient
126```
127
128## Bazel
129
130If you prefer to use Bazel:
131```
132(With Bazel v0.8.0 or above.)
133$ bazel build :hello-world-server :hello-world-client
134$ # Run the server:
135$ bazel-bin/hello-world-server
136$ # In another terminal run the client
137$ bazel-bin/hello-world-client
138```
139
140Unit test examples
141==============================================
142
143Examples for unit testing gRPC clients and servers are located in [examples/src/test](src/test).
144
145In general, we DO NOT allow overriding the client stub.
146We encourage users to leverage `InProcessTransport` as demonstrated in the examples to
147write unit tests. `InProcessTransport` is light-weight and runs the server
148and client in the same process without any socket/TCP connection.
149
150For testing a gRPC client, create the client with a real stub
151using an
152[InProcessChannel](../core/src/main/java/io/grpc/inprocess/InProcessChannelBuilder.java),
153and test it against an
154[InProcessServer](../core/src/main/java/io/grpc/inprocess/InProcessServerBuilder.java)
155with a mock/fake service implementation.
156
157For testing a gRPC server, create the server as an InProcessServer,
158and test it against a real client stub with an InProcessChannel.
159
160The gRPC-java library also provides a JUnit rule,
161[GrpcServerRule](../testing/src/main/java/io/grpc/testing/GrpcCleanupRule.java), to do the graceful
162shutdown boilerplate for you.
163