Skip to content

Readme.md

Latest commit

 

History

History
328 lines (227 loc) · 8.32 KB

Readme.md

File metadata and controls

328 lines (227 loc) · 8.32 KB

go‑grpc‑micro

A lightweight micro‑service playground written in Go that demonstrates how to combine gRPC, GraphQL, WebSockets, Docker, and Elasticsearch. It contains four independent services:

Service Responsibility Port How to start
Account Manage user accounts (PostgreSQL) 8080 docker-compose up account
Catalog Store product catalogue (Elasticsearch) 8080 docker-compose up catalog
Order Create & retrieve orders (PostgreSQL) 8080 docker-compose up order
GraphQL Aggregated API for the above services (gRPC + WebSocket) 8000 docker-compose up graphql

The GraphQL API is the entry point for most consumers (http://localhost:8000). All services are network‑isolated inside Docker, so no local ports are required except for the GraphQL endpoint.

NOTE

  • The repository does not ship a license. Please contact the maintainer before commercial use.
  • Author, version, and description are not defined in the repo. Use the information above to get started.

✨ Features

  • Micro‑service architecture – each domain is an isolated Docker container.
  • gRPC services – fast binary APIs for internal communication.
  • GraphQL façade – a single HTTP endpoint that aggregates data from all services.
  • WebSocket support – real‑time subscriptions through GraphQL (currently not used, but wired).
  • Containerised databases – PostgreSQL for account/order data, Elasticsearch for catalog.
  • Automated build – docker-compose manages build contexts and dependencies.
  • Simple authentication – (placeholder) environment variables; extend with JWT if needed.

🛠 Tech Stack

Category Tool / Library
Language Go 1.24.3
GraphQL (https://github.com/99designs/gqlgen)
gRPC google.golang.org/grpc
Database PostgreSQL (account & order), Elasticsearch 6.2.4
Containerisation Docker / docker‑compose
Utilities envconfig, retry, ksuid, vektah gqlparser

🚀 Getting Started

Prerequisites

Item Version How to install
Git 2.17+ https://git-scm.com
Docker Engine 20.10+ https://docs.docker.com/engine/install/
Docker Compose 1.29+ https://docs.docker.com/compose/install/
Go 1.24.3 https://golang.org/doc/install
Make 4.3+ (optional, for convenience)

Tip – On macOS you can install Docker Desktop which bundles Docker Engine and Compose.

Installation

# 1️⃣  Clone the repo
git clone https://github.com/Adityaadpandey/go-grpc-micro.git
cd go-grpc-micro

# 2️⃣  Install Go dependencies
go mod tidy

The Go modules will pull the required packages for the services.

Configuration

All services read configuration from environment variables. The docker-compose.yaml file already sets them, but if you run a service manually you need to provide the following:

Service Variable Example
Account / Order DATABASE_URL postgres://user:pass@host:5432/dbname?sslmode=disable
Catalog DATABASE_URL http://elasticsearch:9200
GraphQL ACCOUNT_SERVICE_URL, CATALOG_SERVICE_URL, ORDER_SERVICE_URL account:8080 (Docker internal hostname)

When using Docker Compose, these are set automatically.

🎯 Usage

Development Mode

# Start all services in the background
docker-compose up -d

# Tail logs of all containers
docker-compose logs -f

The GraphQL API will be reachable at http://localhost:8000. The gRPC services are listening on account:8080, catalog:8080, and order:8080 inside the Docker network.

Production Mode

For a production‑grade deployment you should:

  1. Build the images ahead of time (docker-compose build).
  2. Use a reverse proxy (NGINX, Traefik) in front of the GraphQL endpoint.
  3. Persist PostgreSQL data using named volumes or an external database.
  4. Secure the gRPC endpoints with TLS (not currently configured).

📚 API Documentation

GraphQL API

The GraphQL schema is generated by gqlgen and lives in graphql/schema.graphqls. Typical queries/mutations:

# Query all products from the catalog
query {
  products {
    id
    name
    description
    price
  }
}

# Create an order
mutation {
  createOrder(accountId: "acct_123", products: [
    { productId: "p_001", quantity: 2 },
    { productId: "p_003", quantity: 1 }
  ]) {
    id
    createdAt
    totalPrice
    accountId
  }
}

# Fetch orders for an account
query {
  ordersByAccount(accountId: "acct_123") {
    id
    createdAt
    totalPrice
  }
}

Note: The GraphQL server also exposes a WebSocket endpoint (/graphql) for subscriptions (future‑proofed).

gRPC API

The Order service gRPC definition is in order/pb/order.proto. A minimal client in Go:

package main

import (
    "context"
    "log"
    "time"

    "github.com/adityaadpandey/go-grpc-micro/order"
    "github.com/adityaadpandey/go-grpc-micro/order/pb"
)

func main() {
    c, err := order.NewClient("localhost:8080") // replace with actual host:port
    if err != nil { log.Fatal(err) }
    defer c.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    // Create an order
    resp, err := c.PostOrder(ctx, "acct_123", order.OrderedProduct{
        {ID: "p_001", Quantity: 2},
        {ID: "p_003", Quantity: 1},
    })
    if err != nil { log.Fatal(err) }

    log.Printf("Order created: %+v", resp)
}

For the other services (Account, Catalog) you would similarly use the generated protobuf client.

🐳 Docker Deployment

# Build all images
docker-compose build

# Bring up everything
docker-compose up

# Stop
docker-compose down

If you want to run a single service:

docker-compose up account          # Account service only
docker-compose up order account catalog  # Order + dependencies

Persisting Data

  • PostgreSQL containers expose a named volume (account_db / order_db) that stores the data on the host.
  • Elasticsearch stores data in its own data directory; you can add a volume mapping if you want to keep it outside the container.

👨‍💻 Development

Project Structure

go-grpc-micro/
├── account/        # Account service (Go + PostgreSQL)
├── catalog/        # Catalog service (Elasticsearch)
├── graphql/        # GraphQL façade (gqlgen)
├── order/          # Order service (Go + PostgreSQL)
├── docker-compose.yaml
├── go.mod
├── go.sum
└── README.md

Building & Running Locally

You can run each service directly with go run (requires Docker‑enabled database locally).

# Account
cd account
go run ./cmd/account

# Order
cd order
go run ./cmd/order

# Catalog
cd catalog
go run ./cmd/catalog

# GraphQL
cd graphql
go run ./cmd/graphql

Ensure the environment variables are set as described in Configuration.

Testing

No automated tests are included in this repository. If you add tests, run them with:

go test ./...

Linting & Formatting

go fmt ./...
go vet ./...

🤝 Contributing

  1. Fork the repository.
  2. Create a feature branch (git checkout -b feature/awesome-feature).
  3. Commit your changes (git commit -m "Add awesome feature").
  4. Push the branch (git push origin feature/awesome-feature).
  5. Open a Pull Request.

Please follow Go conventions (gofmt) and keep the Docker configuration minimal.

📄 License

This project does not include an explicit license. If you plan to use or distribute this code, please contact the author for clarification.

🆘 Support

  • Check the Issues tab on GitHub for known bugs or feature requests.
  • If you encounter a new issue, open a detailed ticket with logs and environment details.
  • For community help, join relevant Go or gRPC discussion forums.

Project Complexity: Medium • Setup Time: 15‑30 min • Maintenance: Stable (no active tests)

🛠️ Built with passion by NOVA 💙 — a product by Aditya

sudo docker compose logs frontend --tail=50 sudo docker compose logs graphql --tail=20 sudo docker compose logs account --tail=20