From 66ef26872d70a00c17d7fc30da18433e7d12afe5 Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Sun, 5 Apr 2026 21:41:44 +0800 Subject: [PATCH] docs: merge "Using ColdBrew" into "Getting Started" The two pages had significant overlap (project structure, proto API, service implementation, running). Merged the unique content from USING.md (config env vars table, adding interceptors) into quickstart.md and deleted USING.md. --- Index.md | 1 - USING.md | 131 --------------------------------------- quickstart.md | 34 +++++++++- tests/navigation.spec.ts | 1 - 4 files changed, 33 insertions(+), 134 deletions(-) delete mode 100644 USING.md diff --git a/Index.md b/Index.md index b7b9f23..bb5afa8 100644 --- a/Index.md +++ b/Index.md @@ -165,7 +165,6 @@ ColdBrew composes proven Go libraries — not replacements: ## Next Steps - **[Getting Started](/getting-started)** — Create your first ColdBrew service -- **[Using ColdBrew](/using)** — Configure and extend your service - **[How-To Guides](/howto)** — Step-by-step guides for common tasks - **[Production Deployment](/howto/production)** — Kubernetes, health probes, tracing, and graceful shutdown - **[Integrations](/integrations)** — Set up monitoring, tracing, and error tracking diff --git a/USING.md b/USING.md deleted file mode 100644 index 2ef61c4..0000000 --- a/USING.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -layout: default -title: "Using ColdBrew" -nav_order: 4 -description: "How to use ColdBrew in your Go microservices" -permalink: /using ---- -# Using ColdBrew -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - -This guide covers how to use ColdBrew after you have created a project. If you haven't created a project yet, see the [Getting Started](/getting-started) guide. - -## Project Structure - -A ColdBrew project generated from the [cookiecutter template](https://github.com/go-coldbrew/cookiecutter-coldbrew) has the following structure: - -``` -MyApp/ - proto/ # Protocol buffer definitions - myapp.proto - service/ # gRPC service implementation - service.go - service_test.go - healthcheck.go - healthcheck_test.go - config/ - config.go # Configuration via environment variables - version/ - version.go # Build-time version info - main.go # Entry point - Makefile # Build, test, lint, run targets - Dockerfile # Production container - go.mod -``` - -## Defining Your API - -ColdBrew services are defined using Protocol Buffers. Edit your `.proto` file to add new RPC methods: - -```protobuf -service MySvc { - rpc SayHello (SayHelloRequest) returns (SayHelloResponse) { - option (google.api.http) = { - get: "/api/v1/hello" - }; - } -} -``` - -The `google.api.http` annotation automatically creates a REST endpoint via grpc-gateway. - -After editing your proto file, regenerate the Go code: - -```shell -make generate -``` - -## Implementing Your Service - -Implement the generated gRPC interface in your `service/service.go`: - -```go -func (s *svcNameImpl) SayHello(ctx context.Context, req *pb.SayHelloRequest) (*pb.SayHelloResponse, error) { - return &pb.SayHelloResponse{ - Message: "Hello " + req.GetName(), - }, nil -} -``` - -Your service struct implements `core.CBService`, which requires two methods: - -- **`InitHTTP(ctx context.Context, mux *runtime.ServeMux, endpoint string, opts []grpc.DialOption)`** — Registers HTTP/REST handlers -- **`InitGRPC(ctx context.Context, s *grpc.Server)`** — Registers gRPC handlers - -## Running Your Service - -```shell -make run -``` - -This starts the service with: -- gRPC server on port `9090` (default) -- HTTP gateway on port `9091` (default) -- Prometheus metrics at `/metrics` -- Health check at `/healthcheck` and `/readycheck` -- pprof debug endpoints at `/debug/pprof/` - -## Configuration - -ColdBrew uses environment variables for configuration. Common settings: - -| Variable | Default | Description | -|----------|---------|-------------| -| `GRPC_PORT` | `9090` | gRPC server port | -| `HTTP_PORT` | `9091` | HTTP gateway port | -| `LOG_LEVEL` | `info` | Log level (debug, info, warn, error) | -| `JSON_LOGS` | `true` | JSON formatted logs | -| `ENVIRONMENT` | `""` | Environment name | -| `TRACE_HEADER_NAME` | `x-trace-id` | Header name for trace propagation | -| `NEW_RELIC_APPNAME` | `""` | New Relic application name | -| `NEW_RELIC_LICENSE_KEY` | `""` | New Relic license key | -| `SENTRY_DSN` | `""` | Sentry DSN for error tracking | - -See the **[Configuration Reference](/config-reference)** for the complete list of 40+ environment variables including gRPC keepalive, TLS, OpenTelemetry OTLP, Prometheus histogram buckets, and graceful shutdown tuning. - -## Adding Interceptors - -ColdBrew comes with a comprehensive set of [interceptors](/howto/interceptors) pre-configured. To add custom interceptors: - -```go -import "github.com/go-coldbrew/interceptors" - -func init() { - interceptors.AddUnaryServerInterceptor(myCustomInterceptor) -} -``` - -{: .warning } -Interceptor configuration functions must be called during `init()` — they are not safe for concurrent use. - -## What's Next? - -- [How-To Guides](/howto) — Detailed guides for tracing, logging, metrics, error handling, and more -- [Integrations](/integrations) — Setting up New Relic, Prometheus, Sentry, and other integrations -- [Packages](/packages) — Browse all ColdBrew packages diff --git a/quickstart.md b/quickstart.md index 42985be..7eb7256 100644 --- a/quickstart.md +++ b/quickstart.md @@ -317,6 +317,39 @@ Three jobs in a single `test` stage: Go module caching is enabled for faster builds. +## Configuration + +ColdBrew uses environment variables for configuration. Common settings: + +| Variable | Default | Description | +|----------|---------|-------------| +| `GRPC_PORT` | `9090` | gRPC server port | +| `HTTP_PORT` | `9091` | HTTP gateway port | +| `LOG_LEVEL` | `info` | Log level (debug, info, warn, error) | +| `JSON_LOGS` | `true` | JSON formatted logs | +| `ENVIRONMENT` | `""` | Environment name | +| `TRACE_HEADER_NAME` | `x-trace-id` | Header name for trace propagation | +| `NEW_RELIC_APPNAME` | `""` | New Relic application name | +| `NEW_RELIC_LICENSE_KEY` | `""` | New Relic license key | +| `SENTRY_DSN` | `""` | Sentry DSN for error tracking | + +See the **[Configuration Reference](/config-reference)** for the complete list of 40+ environment variables including gRPC keepalive, TLS, OpenTelemetry OTLP, Prometheus histogram buckets, and graceful shutdown tuning. + +## Adding Interceptors + +ColdBrew comes with a comprehensive set of [interceptors](/howto/interceptors) pre-configured. To add custom interceptors: + +```go +import "github.com/go-coldbrew/interceptors" + +func init() { + interceptors.AddUnaryServerInterceptor(myCustomInterceptor) +} +``` + +{: .warning } +Interceptor configuration functions must be called during `init()` — they are not safe for concurrent use. + ## What's Built In (You Didn't Have to Configure) Everything below was set up automatically by ColdBrew: @@ -463,7 +496,6 @@ Your service starts on `:9090` (gRPC) and `:9091` (HTTP) with metrics, health ch ## Next Steps -- **[Using ColdBrew](/using)** — Configure ports, environment variables, and interceptors - **[How-To Guides](/howto)** — Tracing, logging, metrics, error handling, and more - **[Production Deployment](/howto/production)** — Kubernetes manifests, health probes, tracing, and graceful shutdown - **[Integrations](/integrations)** — Connect New Relic, Prometheus, Sentry, Jaeger diff --git a/tests/navigation.spec.ts b/tests/navigation.spec.ts index cfbada7..a3759d7 100644 --- a/tests/navigation.spec.ts +++ b/tests/navigation.spec.ts @@ -3,7 +3,6 @@ import { test, expect } from "@playwright/test"; const topLevelPages = [ { path: "/", title: "ColdBrew" }, { path: "/getting-started/", title: "Getting Started" }, - { path: "/using/", title: "Using ColdBrew" }, { path: "/architecture/", title: "Architecture" }, { path: "/howto/", title: "How To" }, { path: "/integrations/", title: "Integrations" },