ContextQMD
Back to Go Micro

Configuration

internal/website/docs/config.md

5.19.14.4 KB
Original Source

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

ComponentVariableExamplePurpose
RegistryMICRO_REGISTRYMICRO_REGISTRY=consulSelect registry implementation
Registry AddressMICRO_REGISTRY_ADDRESSMICRO_REGISTRY_ADDRESS=127.0.0.1:8500Point to registry service
BrokerMICRO_BROKERMICRO_BROKER=natsSelect broker implementation
Broker AddressMICRO_BROKER_ADDRESSMICRO_BROKER_ADDRESS=nats://localhost:4222Broker endpoint
TransportMICRO_TRANSPORTMICRO_TRANSPORT=natsSelect transport implementation
Transport AddressMICRO_TRANSPORT_ADDRESSMICRO_TRANSPORT_ADDRESS=nats://localhost:4222Transport endpoint
StoreMICRO_STOREMICRO_STORE=postgresSelect store implementation
Store DatabaseMICRO_STORE_DATABASEMICRO_STORE_DATABASE=appLogical database name
Store TableMICRO_STORE_TABLEMICRO_STORE_TABLE=recordsDefault table/collection
Store AddressMICRO_STORE_ADDRESSMICRO_STORE_ADDRESS=postgres://user:pass@localhost:5432/app?sslmode=disableConnection string
Server AddressMICRO_SERVER_ADDRESSMICRO_SERVER_ADDRESS=:8080Bind 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:[email protected]:5432/app?sslmode=disable

Load with your process manager or container orchestrator.

Troubleshooting

SymptomCauseFix
Service starts with memory store unexpectedlyEnv vars not exported`env
Consul errors about connection refusedWrong address/portCheck MICRO_REGISTRY_ADDRESS value
NATS connection timeoutServer not runningStart NATS or change address
Postgres SSL errorsMissing sslmode paramAppend ?sslmode=disable locally