mBank

mBank is a compact Go reference project that demonstrates gRPC over mutual TLS (mTLS) with an ECC-only certificate workflow.

It combines a gRPC banking service, a demo client, local certificate generation, Docker support, health checks, graceful shutdown, and observability interceptors into one small codebase that is easy to run and inspect.

mBank is a demo and learning project. It is designed to showcase transport security, service composition, and developer workflow patterns rather than real-world banking rules.

Table of Contents

• About
• Highlights
• Quick Start
• Docker Compose
• Project Layout
• Configuration
• Development
• Troubleshooting
• Contributing
• License

About

mBank shows how to build and test a secure gRPC service in Go with a clean internal structure.

The project demonstrates how to:

• authenticate both the client and server with mTLS
• generate local ECC certificates with OpenSSL
• expose the standard gRPC health service
• shut the server down gracefully on SIGINT and SIGTERM
• collect structured request logs and in-memory RPC metrics
• validate transport behavior with end-to-end integration tests

The demo client connects to the server, performs a health check, creates an account, deposits funds, reads the balance, and withdraws funds.

Highlights

• Go 1.24 project with protobuf and gRPC contracts
• ECC-only local certificate workflow via ./generate-certs.sh
• Enforced client certificate verification on the gRPC server
• Integer-cent money representation on the wire and in service logic
• Structured slog request logging and interceptor-based metrics
• Graceful shutdown and built-in gRPC health checks
• Local binaries, container images, and Docker Compose support
• Unit tests and integration tests for secure and insecure transport paths

Quick Start

Requirements

• Go 1.24+
• OpenSSL
• Docker and Docker Compose (optional)

1. Clone the Repository

git clone https://github.com/liambeeton/go-grpc-over-mtls.git
cd go-grpc-over-mtls

2. Generate ECC Certificates

./generate-certs.sh

This creates a local certs/ directory containing:

• a development CA certificate and private key
• a server certificate and private key
• a client certificate and private key

3. Build the Binaries

make build

4. Start the Server

make run

5. Run the Demo Client

In another terminal:

make run-client

The client will:

• connect to the server over mTLS
• confirm the gRPC health endpoint is SERVING
• create a fresh demo account
• deposit 10000 cents
• fetch the current balance
• withdraw 5000 cents

Docker Compose

Generate certificates first, then run the stack with Docker Compose:

export PORT=8443
docker compose up --build

The compose setup mounts ./certs into both containers and defaults to the certificate paths under /usr/bin/certs.

If you already export certificate-related environment variables in your shell, Docker Compose will use those values instead of the file defaults in docker-compose.yml.

Project Layout

cmd/client              Demo client entrypoint
cmd/server              Server entrypoint
internal/bank           Banking service implementation
internal/config         Shared CLI and environment configuration
internal/money          Money helpers based on integer cents
internal/observability  gRPC logging and metrics interceptors
internal/serverapp      Server bootstrap, health, and shutdown behavior
internal/transport      TLS and insecure transport wiring
pb/                     Protobuf contracts and generated bindings

Configuration

Both the client and server read configuration from flags or environment variables.

Shared Settings

• HOST: client target host or server bind address
• PORT: TCP port for the gRPC connection
• TLS_ENABLED: enables or disables TLS, defaults to true
• CA_FILE: path to the PEM-encoded CA certificate
• CERT_FILE: path to the PEM-encoded certificate for the running process
• KEY_FILE: path to the PEM-encoded private key for the running process

Example Client Environment

export HOST="localhost"
export PORT="8443"
export TLS_ENABLED="true"
export CA_FILE="$PWD/certs/ca.crt"
export CERT_FILE="$PWD/certs/client.crt"
export KEY_FILE="$PWD/certs/client.key"

For the server, point CERT_FILE and KEY_FILE at certs/server.crt and certs/server.key.

Development

Common Commands

go test ./...
go test -race ./...
make lint
make prettier-check
make markdownlint
make proto-compile

Notes

• The client performs a health check before issuing banking RPCs.
• The server exposes the standard gRPC health service and shuts down gracefully.
• Integration tests generate ephemeral ECDSA certificates in Go instead of relying on files in certs/.
• make run and make run-client use the local certs/ directory by default.

Troubleshooting

• If docker compose resolves an unexpected certificate path, unset CA_FILE, CERT_FILE, and KEY_FILE in your shell and retry.
• If make run-client times out, confirm the server is running and listening on the configured host and port.
• If port 8443 is already in use, stop the conflicting process or override PORT.
• If you regenerate certificates, restart both the server and client so they reload the new files.

Contributing

Issues, improvements, and refactors are welcome. If you plan to make a larger change, it helps to open an issue or discussion first so the direction is clear before implementation starts.

License

This project is licensed under the MIT License.