/internal/website/docs/config.md

layout

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

# 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

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:

MICRO_LOG_LEVEL=debug go run main.go

You will see lines like:

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:

# .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
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
• Getting Started
• Plugins