> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Gateway configuration reference

# Gateway Configuration

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

## Configuration Files

| File                     | Purpose                           |
| ------------------------ | --------------------------------- |
| `config.yaml`            | Default development configuration |
| `config.production.yaml` | Production configuration          |

## Loading Configuration

```bash theme={null}
# Use specific config file
./gateway -config config.yaml

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

## Complete Configuration Reference

```yaml theme={null}
# 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:

| Variable              | Config Path                    | Description                  |
| --------------------- | ------------------------------ | ---------------------------- |
| `PORT`                | `server.port`                  | HTTP server port             |
| `DATABASE_URL`        | `database.dsn`                 | PostgreSQL connection string |
| `WALLET_CORE_ADDRESS` | `wallet_core.address`          | gRPC server address          |
| `JWT_SECRET`          | `auth.jwt_secret`              | JWT signing secret           |
| `AGENT_TS_SECRET`     | `service_auth.agent_ts.secret` | Agent-TS service secret      |
| `AGENT_TS_URL`        | -                              | Agent-TS service URL         |
| `VULT_WEBHOOK_SECRET` | `webhook.vult_hmac_secret`     | VULT webhook HMAC secret     |

## Configuration by Section

<Tabs>
  <Tab title="Server">
    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="Database">
    ```yaml theme={null}
    database:
      dsn: "postgres://user:pass@localhost:5432/olive"
      max_open_conns: 25      # Max open connections
      max_idle_conns: 5       # Max idle connections
      conn_max_lifetime: "5m" # Connection lifetime
    ```
  </Tab>

  <Tab title="Wallet-Core">
    ```yaml theme={null}
    wallet_core:
      address: "localhost:50051"
      use_tls: true           # Enable TLS
      tls_cert_path: "/certs/ca.crt"
      tls_server_name: "wallet-core"
      timeout: "30s"
      keepalive_time: "30s"
      keepalive_timeout: "10s"
    ```
  </Tab>

  <Tab title="Rate Limiting">
    ```yaml theme={null}
    rate_limit:
      enabled: true
      requests_per_second: 100  # Max RPS
      burst: 200                # Burst allowance
      by_client: true           # Per-client limits
    ```
  </Tab>
</Tabs>

## Development Configuration

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
tls:
  enabled: true
  cert_file: "/path/to/server.crt"
  key_file: "/path/to/server.key"
```

### gRPC Client TLS (to Wallet-Core)

```yaml theme={null}
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:

| Field                   | Required | Notes                   |
| ----------------------- | -------- | ----------------------- |
| `database.dsn`          | Yes      | Valid PostgreSQL DSN    |
| `auth.jwt_secret`       | Yes      | Minimum 32 characters   |
| `wallet_core.address`   | Yes      | Valid host:port         |
| `service_auth.*.secret` | Yes      | If service auth enabled |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Config file not found">
    * Verify file path is correct
    * Check file permissions
    * Use absolute path with `-config` flag
  </Accordion>

  <Accordion title="Environment variables not expanded">
    * Verify variable is exported
    * Use `${VAR:default}` syntax for defaults
    * Check for typos in variable names
  </Accordion>

  <Accordion title="Database connection failed">
    * Verify DSN format
    * Check network connectivity
    * Ensure database exists
    * Verify credentials
  </Accordion>

  <Accordion title="gRPC connection failed">
    * Verify wallet-core is running
    * Check address and port
    * If TLS enabled, verify certificates
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete endpoint documentation
  </Card>

  <Card title="Deployment" icon="cloud" href="/reference/deployment">
    Production deployment guide
  </Card>
</CardGroup>