Skip to main content

​
Gateway Configuration

The Gateway is configured via YAML files with environment variable expansion support.

​
Configuration Files

FilePurpose
config.yamlDefault development configuration
config.production.yamlProduction configuration

​
Loading Configuration

# Use specific config file
./gateway -config config.yaml

# Production
./gateway -config config.production.yaml

​
Complete Configuration Reference

# Server settings
server:
  host: "0.0.0.0"
  port: ${PORT:8080}
  mode: "release"  # debug, release, test
  read_timeout: "30s"
  write_timeout: "30s"
  shutdown_timeout: "5s"

# Database (for admin, API keys, audit logs)
database:
  dsn: ${DATABASE_URL:postgres://user:pass@localhost:5432/olive}
  max_open_conns: 25
  max_idle_conns: 5
  conn_max_lifetime: "5m"

# Wallet-Core gRPC connection
wallet_core:
  address: ${WALLET_CORE_ADDRESS:localhost:50051}
  use_tls: false
  tls_cert_path: ""
  tls_server_name: ""
  timeout: "30s"
  keepalive_time: "30s"
  keepalive_timeout: "10s"

# Authentication
auth:
  jwt_secret: ${JWT_SECRET}
  jwt_expiry: "24h"
  refresh_token_expiry: "168h"  # 7 days
  api_key_prefix: "olive_live_"

# Service authentication (internal services)
service_auth:
  agent_ts:
    secret: ${AGENT_TS_SECRET}
    name: "agent-ts"
    allowed_endpoints: ["/api/v1/*"]
  pos_service:
    secret: ${POS_SERVICE_SECRET}
    name: "pos-service"

# Rate limiting
rate_limit:
  enabled: true
  requests_per_second: 100
  burst: 200
  by_client: true

# Logging
logging:
  level: "info"  # debug, info, warn, error
  format: "json"
  output: "stdout"
  include_caller: true

# Webhook configuration
webhook:
  vult_hmac_secret: ${VULT_WEBHOOK_SECRET}

# TLS (optional, for HTTPS)
tls:
  enabled: false
  cert_file: ""
  key_file: ""

# Metrics
metrics:
  enabled: true
  path: "/metrics"
  port: 9090

​
Environment Variable Overrides

The following environment variables override configuration:
VariableConfig PathDescription
PORTserver.portHTTP server port
DATABASE_URLdatabase.dsnPostgreSQL connection string
WALLET_CORE_ADDRESSwallet_core.addressgRPC server address
JWT_SECRETauth.jwt_secretJWT signing secret
AGENT_TS_SECRETservice_auth.agent_ts.secretAgent-TS service secret
AGENT_TS_URL-Agent-TS service URL
VULT_WEBHOOK_SECRETwebhook.vult_hmac_secretVULT webhook HMAC secret

​
Configuration by Section

server:
  host: "0.0.0.0"        # Bind address
  port: 8080              # HTTP port
  mode: "release"         # Gin mode
  read_timeout: "30s"     # Request read timeout
  write_timeout: "30s"    # Response write timeout
  shutdown_timeout: "5s"  # Graceful shutdown wait

​
Development Configuration

server:
  port: 8080
  mode: "debug"

database:
  dsn: "postgres://olive:olive@localhost:5432/olive?sslmode=disable"

wallet_core:
  address: "localhost:50051"
  use_tls: false

auth:
  jwt_secret: "development-secret-change-in-production"

logging:
  level: "debug"
  format: "pretty"

rate_limit:
  enabled: false

​
Production Configuration

server:
  port: ${PORT:8080}
  mode: "release"
  read_timeout: "30s"
  write_timeout: "30s"

database:
  dsn: ${DATABASE_URL}
  max_open_conns: 50
  max_idle_conns: 10
  conn_max_lifetime: "10m"

wallet_core:
  address: ${WALLET_CORE_ADDRESS}
  use_tls: true
  tls_cert_path: "/certs/wallet-core-ca.crt"
  tls_server_name: "wallet-core"

auth:
  jwt_secret: ${JWT_SECRET}
  jwt_expiry: "1h"
  refresh_token_expiry: "24h"

logging:
  level: "info"
  format: "json"

rate_limit:
  enabled: true
  requests_per_second: 1000
  burst: 2000

tls:
  enabled: true
  cert_file: "/certs/server.crt"
  key_file: "/certs/server.key"

​
TLS/mTLS Configuration

​
Server TLS

tls:
  enabled: true
  cert_file: "/path/to/server.crt"
  key_file: "/path/to/server.key"

​
gRPC Client TLS (to Wallet-Core)

wallet_core:
  use_tls: true
  tls_cert_path: "/path/to/ca.crt"
  tls_server_name: "wallet-core.svc.cluster.local"

​
Validation

The configuration loader validates required fields:
FieldRequiredNotes
database.dsnYesValid PostgreSQL DSN
auth.jwt_secretYesMinimum 32 characters
wallet_core.addressYesValid host:port
service_auth.*.secretYesIf service auth enabled

​
Troubleshooting

  • Verify file path is correct
  • Check file permissions
  • Use absolute path with -config flag
  • Verify variable is exported
  • Use ${VAR:default} syntax for defaults
  • Check for typos in variable names
  • Verify DSN format
  • Check network connectivity
  • Ensure database exists
  • Verify credentials
  • Verify wallet-core is running
  • Check address and port
  • If TLS enabled, verify certificates

​
Next Steps

API Reference

Complete endpoint documentation

Deployment

Production deployment guide