update the docs to easily navigate

2025-11-23 21:44:41 +02:00 · 2025-11-13 18:59:34 +00:00
parent 8cda829320
commit 06b31f545a
9 changed files with 373 additions and 0 deletions
--- a/internal/website/docs/architecture.md
+++ b/internal/website/docs/architecture.md
@@ -45,6 +45,12 @@ in the plugins repo. State and persistence becomes a core requirement beyond pro

 We will share more on architecture soon

+## Related
+
+- [ADR Index](architecture/index.md)
+- [Configuration](config.md)
+- [Plugins](plugins.md)
+
 ## Example Usage

 Here's a minimal Go Micro service demonstrating the architecture:
--- a/internal/website/docs/architecture/adr-009-progressive-configuration.md
+++ b/internal/website/docs/architecture/adr-009-progressive-configuration.md
@@ -150,3 +150,4 @@ func (s *service) Init() error {
 - [ADR-004: mDNS as Default Registry](adr-004-mdns-default-registry.md)
 - ADR-008: Environment Variable Support (planned)
 - [Getting Started Guide](../getting-started.md) - Configuration examples
+ - [Configuration Guide](../config.md)
--- a/internal/website/docs/architecture/adr-template.md
+++ b/internal/website/docs/architecture/adr-template.md
@@ -0,0 +1,37 @@
+---
+layout: default
+---
+
+# ADR-XXX: Title
+
+Status: Proposed  
+Date: YYYY-MM-DD
+
+## Context
+
+Describe the problem, forces, and constraints leading to the decision.
+
+## Decision
+
+State the decision clearly and precisely.
+
+## Consequences
+
+Positive and negative outcomes, trade-offs introduced by this decision.
+
+## Alternatives Considered
+
+1. Alternative A - why rejected
+2. Alternative B - why rejected
+
+## Implementation Notes
+
+High-level steps or rollout plan if accepted.
+
+## Related
+
+- Link other ADRs, documentation, or issues.
+
+## References
+
+External resources, prior art, research.
--- a/internal/website/docs/config.md
+++ b/internal/website/docs/config.md
@@ -0,0 +1,128 @@
+---
+layout: default
+---
+
+# Configuration
+
+Go Micro follows a progressive configuration model so you can start with zero setup and layer in complexity only when needed.
+
+## Levels of Configuration
+
+1. Zero Config (Defaults)
+   - mDNS registry, HTTP transport, in-memory broker/store
+2. Environment Variables
+   - Override core components without code changes
+3. Code Options
+   - Fine-grained control via functional options
+4. External Sources (Future / Plugins)
+   - Configuration loaded from files, vaults, or remote services
+
+## Core Environment Variables
+
+| Component | Variable | Example | Purpose |
+|-----------|----------|---------|---------|
+| Registry  | `MICRO_REGISTRY` | `MICRO_REGISTRY=consul` | Select registry implementation |
+| Registry Address | `MICRO_REGISTRY_ADDRESS` | `MICRO_REGISTRY_ADDRESS=127.0.0.1:8500` | Point to registry service |
+| Broker    | `MICRO_BROKER` | `MICRO_BROKER=nats` | Select broker implementation |
+| Broker Address | `MICRO_BROKER_ADDRESS` | `MICRO_BROKER_ADDRESS=nats://localhost:4222` | Broker endpoint |
+| Transport | `MICRO_TRANSPORT` | `MICRO_TRANSPORT=nats` | Select transport implementation |
+| Transport Address | `MICRO_TRANSPORT_ADDRESS` | `MICRO_TRANSPORT_ADDRESS=nats://localhost:4222` | Transport endpoint |
+| Store     | `MICRO_STORE` | `MICRO_STORE=postgres` | Select store implementation |
+| Store Database | `MICRO_STORE_DATABASE` | `MICRO_STORE_DATABASE=app` | Logical database name |
+| Store Table | `MICRO_STORE_TABLE` | `MICRO_STORE_TABLE=records` | Default table/collection |
+| Store Address | `MICRO_STORE_ADDRESS` | `MICRO_STORE_ADDRESS=postgres://user:pass@localhost:5432/app?sslmode=disable` | Connection string |
+| Server Address | `MICRO_SERVER_ADDRESS` | `MICRO_SERVER_ADDRESS=:8080` | Bind address for RPC server |
+
+## Example: Switching Components via Env Vars
+
+```bash
+# Use NATS for broker and transport, Consul for registry
+export MICRO_BROKER=nats
+export MICRO_TRANSPORT=nats
+export MICRO_REGISTRY=consul
+export MICRO_REGISTRY_ADDRESS=127.0.0.1:8500
+
+# Run your service
+go run main.go
+```
+
+No code changes required. The framework internally wires the selected implementations.
+
+## Equivalent Code Configuration
+
+```go
+service := micro.NewService(
+    micro.Name("helloworld"),
+    micro.Broker(nats.NewBroker()),
+    micro.Transport(natstransport.NewTransport()),
+    micro.Registry(consul.NewRegistry(registry.Addrs("127.0.0.1:8500"))),
+)
+service.Init()
+```
+
+Use env vars for deployment level overrides; use code options for explicit control or when composing advanced setups.
+
+## Precedence Rules
+
+1. Explicit code options always win
+2. If not set in code, env vars are applied
+3. If neither code nor env vars set, defaults are used
+
+## Discoverability Strategy
+
+Defaults allow local development with zero friction. As teams scale:
+- Introduce env vars for staging/production parity
+- Consolidate secrets (e.g. store passwords) using external secret managers (future guide)
+- Move to service mesh aware registry (Consul/NATS JetStream)
+
+## Validating Configuration
+
+Enable debug logging to confirm selected components:
+
+```bash
+MICRO_LOG_LEVEL=debug go run main.go
+```
+
+You will see lines like:
+
+```text
+Registry [consul] Initialised
+Broker [nats] Connected
+Transport [nats] Listening on nats://localhost:4222
+Store [postgres] Connected to app/records
+```
+
+## Patterns
+
+### Twelve-Factor Alignment
+Environment variables map directly to deploy-time configuration. Avoid hardcoding component choices so services remain portable.
+
+### Multi-Environment Setup
+Use a simple env file per environment:
+
+```bash
+# .env.staging
+MICRO_REGISTRY=consul
+MICRO_REGISTRY_ADDRESS=consul.staging.internal:8500
+MICRO_BROKER=nats
+MICRO_BROKER_ADDRESS=nats.staging.internal:4222
+MICRO_STORE=postgres
+MICRO_STORE_ADDRESS=postgres://staging:pass@pg.staging.internal:5432/app?sslmode=disable
+```
+
+Load with your process manager or container orchestrator.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Service starts with memory store unexpectedly | Env vars not exported | `env | grep MICRO_STORE` to verify |
+| Consul errors about connection refused | Wrong address/port | Check `MICRO_REGISTRY_ADDRESS` value |
+| NATS connection timeout | Server not running | Start NATS or change address |
+| Postgres SSL errors | Missing sslmode param | Append `?sslmode=disable` locally |
+
+## Related
+
+- [ADR-009: Progressive Configuration](architecture/adr-009-progressive-configuration.md)
+- [Getting Started](getting-started.md)
+- [Plugins](plugins.md)
--- a/internal/website/docs/contributing.md
+++ b/internal/website/docs/contributing.md
@@ -0,0 +1,65 @@
+---
+layout: default
+---
+
+# Contributing
+
+This is a rendered copy of the repository `CONTRIBUTING.md` for convenient access via the documentation site.
+
+## Overview
+
+Go Micro welcomes contributions of all kinds: code, documentation, examples, and plugins.
+
+## Quick Start
+
+```bash
+git clone https://github.com/micro/go-micro.git
+cd go-micro
+go mod download
+go test ./...
+```
+
+## Process
+
+1. Fork and create a feature branch
+2. Make focused changes with tests
+3. Run linting and full test suite
+4. Open a PR describing motivation and approach
+
+## Commit Format
+
+Use conventional commits:
+
+```
+feat(registry): add consul health check
+fix(broker): prevent reconnect storm
+```
+
+## Testing
+
+Run unit tests:
+```bash
+go test ./...
+```
+Run race/coverage:
+```bash
+go test -race -coverprofile=coverage.out ./...
+```
+
+## Plugins
+
+Place new plugins under the appropriate interface directory (e.g. `registry/consul/`). Include tests and usage examples. Document env vars and options.
+
+## Documentation
+
+Docs live in `internal/website/docs/`. Add new examples under `internal/website/docs/examples/`.
+
+## Help & Questions
+
+Use GitHub Discussions or the issue templates. For general usage questions open a "Question" issue.
+
+## Full Guide
+
+For complete details see the repository copy of the guide on GitHub.
+
+- View on GitHub: https://github.com/micro/go-micro/blob/master/CONTRIBUTING.md
--- a/internal/website/docs/examples/index.md
+++ b/internal/website/docs/examples/index.md
@@ -12,3 +12,7 @@ A collection of small, focused examples demonstrating common patterns with Go Mi
 - [Service Discovery with Consul](registry-consul.md)
 - [State with Postgres Store](store-postgres.md)
 - [NATS Transport](transport-nats.md)
+
+## More
+
+- [Real-World Examples](realworld/index.md)
--- a/internal/website/docs/index.md
+++ b/internal/website/docs/index.md
@@ -27,6 +27,7 @@ about the framework.

 - [Getting Started](getting-started.md)
 - [Architecture](architecture.md)
+- [Configuration](config.md)
 - [Registry](registry.md)
 - [Broker](broker.md)
 - [Client/Server](client-server.md)
@@ -42,3 +43,6 @@ about the framework.
 - [Architecture Decisions](architecture/index.md)
 - [Real-World Examples](examples/realworld/index.md)
 - [Migration Guides](guides/migration/index.md)
+- [Observability](observability.md)
+- [Contributing](contributing.md)
+- [Roadmap](roadmap.md)
--- a/internal/website/docs/observability.md
+++ b/internal/website/docs/observability.md
@@ -0,0 +1,93 @@
+---
+layout: default
+---
+
+# Observability
+
+Observability in Go Micro spans logs, metrics, and traces. The goal is rapid insight into service behavior with minimal configuration.
+
+## Core Principles
+
+1. Structured Logs – Machine-parsable, leveled output
+2. Metrics – Quantitative trends (counters, gauges, histograms)
+3. Traces – Request flows across service boundaries
+4. Correlation – IDs flowing through all three signals
+
+## Logging
+
+The default logger can be replaced. Use env vars to adjust level:
+
+```bash
+MICRO_LOG_LEVEL=debug go run main.go
+```
+
+Recommended fields:
+- `service` – service name
+- `version` – release identifier
+- `trace_id` – propagated context id
+- `span_id` – current operation id
+
+## Metrics
+
+Patterns:
+- Emit counters for request totals
+- Use histograms for latency
+- Track error rates per endpoint
+
+Example (pseudo-code):
+
+```go
+// Wrap handler to record metrics
+func MetricsWrapper(fn micro.HandlerFunc) micro.HandlerFunc {
+    return func(ctx context.Context, req micro.Request, rsp interface{}) error {
+        start := time.Now()
+        err := fn(ctx, req, rsp)
+        latency := time.Since(start)
+        metrics.Inc("requests_total", req.Endpoint(), errorLabel(err))
+        metrics.Observe("request_latency_seconds", latency, req.Endpoint())
+        return err
+    }
+}
+```
+
+## Tracing
+
+Distributed tracing links calls across services.
+
+Propagation strategy:
+- Extract trace context from incoming headers
+- Inject into outgoing RPC calls/broker messages
+- Create spans per handler and client call
+
+## Local Development Strategy
+
+Start with only structured logs. Add metrics when operating multiple services. Introduce tracing once debugging multi-hop latency or failures.
+
+## Roadmap (Planned Enhancements)
+
+- Native OpenTelemetry exporter helpers
+- Automatic handler/client wrapping for spans
+- Default correlation IDs across broker messages
+
+## Deployment Recommendations
+
+| Scale | Suggested Stack |
+|-------|-----------------|
+| Dev   | Console logs only |
+| Staging | Logs + basic metrics (Prometheus) |
+| Prod (basic) | Logs + metrics + sampling traces |
+| Prod (complex) | Full tracing + profiling + anomaly detection |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Missing trace IDs in logs | Context not propagated | Ensure wrappers add IDs |
+| Metrics server empty | Endpoint not scraped | Verify Prometheus config |
+| High cardinality metrics | Dynamic labels | Reduce labeled dimensions |
+
+## Related
+
+- [Getting Started](getting-started.md)
+- [Plugins](plugins.md)
+- [Architecture Decisions](architecture/index.md)
--- a/internal/website/docs/roadmap.md
+++ b/internal/website/docs/roadmap.md
@@ -0,0 +1,35 @@
+---
+layout: default
+---
+
+# Roadmap
+
+This page mirrors the repository `ROADMAP.md` for easy browsing.
+
+## Focus Areas (Q1 2026)
+- Documentation expansion
+- Observability integration (OpenTelemetry planned)
+- Developer tooling improvements
+
+## Highlights
+
+See the full roadmap on GitHub for detailed quarterly goals:
+
+- Production readiness (graceful shutdown, health checks)
+- Cloud native deployment patterns (operator, Helm charts)
+- Security enhancements (mTLS, secrets integration)
+- Plugin ecosystem growth
+
+## Contributing to the Roadmap
+
+Pick an item, open an issue, propose an approach, then submit a PR.
+
+High priority: documentation, examples, performance improvements, plugin development.
+
+## Full Document
+
+View the complete roadmap including long-term vision and version support:
+
+- GitHub: https://github.com/micro/go-micro/blob/master/ROADMAP.md
+
+_Last synced: November 2025_