go-micro.dev/v5@v5.12.0/internal/website/docs/config.md (about)

     1  ---
     2  layout: default
     3  ---
     4  
     5  # Configuration
     6  
     7  Go Micro follows a progressive configuration model so you can start with zero setup and layer in complexity only when needed.
     8  
     9  ## Levels of Configuration
    10  
    11  1. Zero Config (Defaults)
    12     - mDNS registry, HTTP transport, in-memory broker/store
    13  2. Environment Variables
    14     - Override core components without code changes
    15  3. Code Options
    16     - Fine-grained control via functional options
    17  4. External Sources (Future / Plugins)
    18     - Configuration loaded from files, vaults, or remote services
    19  
    20  ## Core Environment Variables
    21  
    22  | Component | Variable | Example | Purpose |
    23  |-----------|----------|---------|---------|
    24  | Registry  | `MICRO_REGISTRY` | `MICRO_REGISTRY=consul` | Select registry implementation |
    25  | Registry Address | `MICRO_REGISTRY_ADDRESS` | `MICRO_REGISTRY_ADDRESS=127.0.0.1:8500` | Point to registry service |
    26  | Broker    | `MICRO_BROKER` | `MICRO_BROKER=nats` | Select broker implementation |
    27  | Broker Address | `MICRO_BROKER_ADDRESS` | `MICRO_BROKER_ADDRESS=nats://localhost:4222` | Broker endpoint |
    28  | Transport | `MICRO_TRANSPORT` | `MICRO_TRANSPORT=nats` | Select transport implementation |
    29  | Transport Address | `MICRO_TRANSPORT_ADDRESS` | `MICRO_TRANSPORT_ADDRESS=nats://localhost:4222` | Transport endpoint |
    30  | Store     | `MICRO_STORE` | `MICRO_STORE=postgres` | Select store implementation |
    31  | Store Database | `MICRO_STORE_DATABASE` | `MICRO_STORE_DATABASE=app` | Logical database name |
    32  | Store Table | `MICRO_STORE_TABLE` | `MICRO_STORE_TABLE=records` | Default table/collection |
    33  | Store Address | `MICRO_STORE_ADDRESS` | `MICRO_STORE_ADDRESS=postgres://user:pass@localhost:5432/app?sslmode=disable` | Connection string |
    34  | Server Address | `MICRO_SERVER_ADDRESS` | `MICRO_SERVER_ADDRESS=:8080` | Bind address for RPC server |
    35  
    36  ## Example: Switching Components via Env Vars
    37  
    38  ```bash
    39  # Use NATS for broker and transport, Consul for registry
    40  export MICRO_BROKER=nats
    41  export MICRO_TRANSPORT=nats
    42  export MICRO_REGISTRY=consul
    43  export MICRO_REGISTRY_ADDRESS=127.0.0.1:8500
    44  
    45  # Run your service
    46  go run main.go
    47  ```
    48  
    49  No code changes required. The framework internally wires the selected implementations.
    50  
    51  ## Equivalent Code Configuration
    52  
    53  ```go
    54  service := micro.NewService(
    55      micro.Name("helloworld"),
    56      micro.Broker(nats.NewBroker()),
    57      micro.Transport(natstransport.NewTransport()),
    58      micro.Registry(consul.NewRegistry(registry.Addrs("127.0.0.1:8500"))),
    59  )
    60  service.Init()
    61  ```
    62  
    63  Use env vars for deployment level overrides; use code options for explicit control or when composing advanced setups.
    64  
    65  ## Precedence Rules
    66  
    67  1. Explicit code options always win
    68  2. If not set in code, env vars are applied
    69  3. If neither code nor env vars set, defaults are used
    70  
    71  ## Discoverability Strategy
    72  
    73  Defaults allow local development with zero friction. As teams scale:
    74  - Introduce env vars for staging/production parity
    75  - Consolidate secrets (e.g. store passwords) using external secret managers (future guide)
    76  - Move to service mesh aware registry (Consul/NATS JetStream)
    77  
    78  ## Validating Configuration
    79  
    80  Enable debug logging to confirm selected components:
    81  
    82  ```bash
    83  MICRO_LOG_LEVEL=debug go run main.go
    84  ```
    85  
    86  You will see lines like:
    87  
    88  ```text
    89  Registry [consul] Initialised
    90  Broker [nats] Connected
    91  Transport [nats] Listening on nats://localhost:4222
    92  Store [postgres] Connected to app/records
    93  ```
    94  
    95  ## Patterns
    96  
    97  ### Twelve-Factor Alignment
    98  Environment variables map directly to deploy-time configuration. Avoid hardcoding component choices so services remain portable.
    99  
   100  ### Multi-Environment Setup
   101  Use a simple env file per environment:
   102  
   103  ```bash
   104  # .env.staging
   105  MICRO_REGISTRY=consul
   106  MICRO_REGISTRY_ADDRESS=consul.staging.internal:8500
   107  MICRO_BROKER=nats
   108  MICRO_BROKER_ADDRESS=nats.staging.internal:4222
   109  MICRO_STORE=postgres
   110  MICRO_STORE_ADDRESS=postgres://staging:pass@pg.staging.internal:5432/app?sslmode=disable
   111  ```
   112  
   113  Load with your process manager or container orchestrator.
   114  
   115  ## Troubleshooting
   116  
   117  | Symptom | Cause | Fix |
   118  |---------|-------|-----|
   119  | Service starts with memory store unexpectedly | Env vars not exported | `env | grep MICRO_STORE` to verify |
   120  | Consul errors about connection refused | Wrong address/port | Check `MICRO_REGISTRY_ADDRESS` value |
   121  | NATS connection timeout | Server not running | Start NATS or change address |
   122  | Postgres SSL errors | Missing sslmode param | Append `?sslmode=disable` locally |
   123  
   124  ## Related
   125  
   126  - [ADR-009: Progressive Configuration](architecture/adr-009-progressive-configuration.md)
   127  - [Getting Started](getting-started.md)
   128  - [Plugins](plugins.md)