GUIDES
gRPC Client, Server, and Gateway in Go
A Go gRPC example implementing a simple in-memory key-value store with three components: a gRPC server, a REST-to-gRPC gateway, and a CLI client.
Source: github.com/jecklgamis/go-grpc-example
Features
- gRPC server with
PutandGetoperations backed by an in-memory store - REST gateway via
grpc-gatewaythat proxies HTTP to gRPC - CLI client supporting both plain and TLS connections
- Protobuf-defined API with auto-generated Go stubs
- Docker image bundling all three binaries under
supervisord
Architecture
cmd/
server/ → gRPC server entry point (port 4000)
gateway/ → REST-to-gRPC proxy entry point (port 8080)
client/ → CLI client entry point
pkg/
kvstore/ → kvstore.proto + generated stubs (*.pb.go, *.pb.gw.go)
server/ → in-memory map store implementation
gateway/ → grpc-gateway reverse proxy
client/ → gRPC client wrapper
version/ → build version injected via ldflags
Data flow: REST clients → gateway (:8080) → gRPC server (:4000). gRPC clients connect to the server directly.
Requirements
- Go 1.26+
protoc(Protocol Buffers compiler)
brew install protobuf
protoc --version # should be 3.x or above
Getting Started
# Install protoc Go plugins
make install-deps
# Regenerate protobuf stubs and build all binaries
make build
This produces native and linux/amd64 binaries under bin/:
bin/server bin/server-linux-amd64
bin/gateway bin/gateway-linux-amd64
bin/client bin/client-linux-amd64
Running Locally
Start the gRPC server:
bin/server -port 4000
# 2019/08/13 07:30:24 Started server on port 4000
Start the REST gateway (in a separate terminal):
bin/gateway -port 8080 -grpcServerAddr localhost:4000
# 2019/08/13 08:27:25 Started gateway on port 8080
Use the CLI client:
bin/client -serverAddr localhost:4000 put some-key some-value
bin/client -serverAddr localhost:4000 get some-key
# With TLS (uses InsecureSkipVerify — testing only)
bin/client -serverAddr localhost:4000 -ssl put some-key some-value
REST API (via Gateway)
PUT a key-value pair:
curl -X PUT http://localhost:8080/v1 \
-d '{"key": "some-key", "value": "some-value"}'
GET a value by key:
curl "http://localhost:8080/v1?key=some-key"
HTTP routing rules are defined in pkg/kvstore/kvstore.yaml, not as proto annotations.
Docker
# Build image (requires binaries already built)
make image
# Run container (exposes ports 4000 and 8080)
make run
# Open a shell in the container
make run-bash
Or pull directly:
docker run -p 4000:4000 -p 8080:8080 -it jecklgamis/go-grpc-example:main
Proto Definition
The API is defined in pkg/kvstore/kvstore.proto. After any changes, regenerate stubs with:
make protobufs # generates kvstore.pb.go and kvstore_grpc.pb.go
make gateway-protobufs # generates kvstore.pb.gw.go
Do not edit the generated *.pb.go / *.pb.gw.go files directly.
Source
Full source code available on GitHub: jecklgamis/go-grpc-example