Configuration Reference

OPS Intermediate

Complete reference for all EZ-Console configuration options.

Overview

This document provides a complete reference for all configuration options available in EZ-Console. Configuration can be set via YAML file, environment variables, or command-line flags.

Configuration File Format

Configuration files use YAML format:

server:
  host: "0.0.0.0"
  port: 8080

database:
  driver: "sqlite"
  path: "ez-console.db"

Server Configuration

Basic Server Settings

server:
  host: "0.0.0.0"              # Server host (default: "0.0.0.0")
  port: 8080                    # Server port (default: 8080)
  mode: "release"              # Server mode: "debug" or "release" (default: "release")
  root_url: ""                  # Root URL for reverse proxy (default: "")

Timeouts

server:
  read_timeout: "10s"          # Read timeout (default: "10s")
  write_timeout: "10s"          # Write timeout (default: "10s")
  shutdown_timeout: "10s"       # Graceful shutdown timeout (default: "10s")

File Upload

server:
  file_upload_path: "./uploads" # File upload directory (default: "./uploads")
  max_upload_size: 10485760     # Max upload size in bytes (default: 10MB)

GeoIP

server:
  geoip_db_path: ""             # GeoIP database path (optional)

Database Configuration

SQLite

database:
  driver: "sqlite"
  path: "ez-console.db"         # Database file path
  table_prefix: "t_"            # Table prefix (default: "t_")
  slow_threshold: "3s"          # Slow query threshold (default: "3s")

MySQL

database:
  driver: "mysql"
  host: "localhost"             # Database host
  port: 3306                     # Database port (default: 3306)
  username: "root"               # Database username
  password: "password"          # Database password
  schema: "ez_console"          # Database name
  charset: "utf8mb4"             # Character set (default: "utf8mb4")
  collation: "utf8mb4_unicode_ci" # Collation (default: "utf8mb4_unicode_ci")
  max_open_connections: 100     # Max open connections (default: 100)
  max_idle_connections: 10      # Max idle connections (default: 10)
  max_connection_life_time: "30s" # Max connection lifetime (default: "30s")
  table_prefix: "t_"            # Table prefix (default: "t_")
  slow_threshold: "3s"          # Slow query threshold (default: "3s")

PostgreSQL

database:
  driver: "postgres"
  host: "localhost"             # Database host
  port: 5432                     # Database port (default: 5432)
  username: "postgres"           # Database username
  password: "password"          # Database password
  schema: "ez_console"          # Database name
  max_open_connections: 100     # Max open connections (default: 100)
  max_idle_connections: 10      # Max idle connections (default: 10)
  max_connection_life_time: "30s" # Max connection lifetime (default: "30s")
  table_prefix: "t_"            # Table prefix (default: "t_")
  slow_threshold: "3s"          # Slow query threshold (default: "3s")

ClickHouse

database:
  driver: "clickhouse"
  host: "localhost"             # Database host
  port: 9000                     # Database port (default: 9000)
  username: "default"           # Database username
  password: "password"          # Database password
  schema: "ez_console"          # Database name
  read_timeout: "10s"            # Read timeout (default: "10s")
  dial_timeout: "10s"            # Dial timeout (default: "10s")
  max_execution_time: "60s"      # Max execution time (default: "60s")
  enable_compression: true       # Enable compression (default: true)
  max_open_connections: 100     # Max open connections (default: 100)
  max_idle_connections: 2        # Max idle connections (default: 2)
  max_connection_life_time: "30s" # Max connection lifetime (default: "30s")
  table_prefix: "t_"            # Table prefix (default: "t_")
  slow_threshold: "3s"          # Slow query threshold (default: "3s")

JWT Configuration

jwt:
  secret: "your-jwt-secret"     # JWT secret (auto-generated if not provided)
  expiration: "24h"              # Token expiration (default: "24h")

Logging Configuration

log:
  level: "info"                  # Log level: "debug", "info", "warn", "error" (default: "info")
  format: "json"                 # Log format: "json" or "logfmt" (default: "json")
  path: "logs"                   # Log directory (default: "logs")

OAuth Configuration

oauth:
  enabled: true                  # Enable OAuth (default: false)
  providers:
    - name: "google"             # Provider name
      display_name: "Google"      # Display name
      client_id: "your-client-id" # OAuth client ID
      client_secret: "your-client-secret" # OAuth client secret
      icon_url: "https://example.com/icon.png" # Icon URL (optional)
      auth_url: "https://accounts.google.com/o/oauth2/v2/auth" # Authorization URL
      token_url: "https://oauth2.googleapis.com/token" # Token URL
      user_info_url: "https://www.googleapis.com/oauth2/v2/userinfo" # User info URL
      redirect_url: "http://localhost:5173/login?provider=google" # Redirect URL
      role_field: "role"          # Role field in user info (optional)
      email_field: "email"       # Email field (optional, default: "email")
      username_field: "username" # Username field (optional, default: "username")
      full_name_field: "fullName" # Full name field (optional, default: "fullName")
      avatar_field: "avatar"      # Avatar field (optional, default: "avatar")
      auto_create_user: true      # Auto create user (optional, default: false)

Cache Configuration

cache:
  size: 1000                     # Cache size (default: 1000)

Tracing Configuration

Basic Tracing Settings

tracing:
  service_name: "ez-console"     # Service name for trace identification (required)

HTTP Exporter (OpenTelemetry Collector)

tracing:
  service_name: "ez-console"
  http:
    endpoint: "localhost:4317"              # Collector endpoint (host:port)
    url_path: "/v1/traces"                  # URL path for traces endpoint (optional)
    timeout: 30s                            # Request timeout (optional)
    insecure: true                          # Skip TLS verification (optional, dev only)
    compression: "gzip"                     # Compression: true/false/1/0/"gzip" (gzip) or false/0/"false" (none) (optional)
    header:                                 # Custom HTTP headers (optional)
      Authorization: "Bearer token123"
    retry:                                  # Retry configuration (optional, default: enabled)
      enabled: true                         # Enable retry (default: true, can be set to "false" to disable)
      initial_interval: 5s                 # Initial retry interval (default: 5s)
      max_interval: 30s                    # Maximum retry interval (default: 30s)
      max_elapsed_time: 1m                 # Maximum total retry time (default: 1m)
    tls_config:                             # TLS configuration (optional)
      cert_file: "/path/to/cert.pem"
      key_file: "/path/to/key.pem"
      ca_file: "/path/to/ca.pem"
      server_name: "collector.example.com"
      insecure_skip_verify: false

gRPC Exporter (OpenTelemetry Collector)

tracing:
  service_name: "ez-console"
  grpc:
    endpoint: "localhost:4318"              # Collector gRPC endpoint (host:port)
    timeout: 30s                            # Request timeout (optional)
    insecure: false                         # Skip TLS verification (optional, dev only)
    compression: "gzip"                     # Compression: true/false/1/0/"gzip" (gzip) or false/0/"false" (none) (optional)
    reconnection_period: 5s                 # Reconnection interval for failures (optional)
    header:                                 # Custom gRPC metadata (optional)
      api-key: "secret-key"
    retry:                                  # Retry configuration (optional, default: enabled)
      enabled: true                         # Enable retry (default: true, can be set to "false" to disable)
      initial_interval: 5s                 # Initial retry interval (default: 5s)
      max_interval: 30s                    # Maximum retry interval (default: 30s)
      max_elapsed_time: 1m                 # Maximum total retry time (default: 1m)
    tls_config:                             # TLS configuration (optional)
      cert_file: "/path/to/cert.pem"
      key_file: "/path/to/key.pem"
      ca_file: "/path/to/ca.pem"
      server_name: "collector.example.com"
      insecure_skip_verify: false
    service_config: ""                      # gRPC service config JSON string (optional)

Zipkin Exporter

tracing:
  service_name: "ez-console"
  zipkin:
    endpoint: "http://localhost:9411/api/v2/spans"  # Zipkin API endpoint

File Exporter

tracing:
  service_name: "ez-console"
  file:
    path: "traces.json"                     # Output file path

Configuration Options Reference

Common:

• service_name (string, required): Service identifier in traces

HTTP Exporter:

• http.endpoint (string, required): Collector endpoint (host:port)
• http.url_path (string, optional): HTTP path for traces (default: /v1/traces)
• http.timeout (duration, optional): Request timeout
• http.insecure (bool, optional): Skip TLS certificate verification
• http.compression (string/bool/int, optional): Compression setting
  • true, "true", 1, "1", "gzip" → gzip compression
  • false, "false", 0, "0" → no compression (default: no compression)
• http.header (map[string]string, optional): Custom HTTP headers
• http.retry (object/string, optional): Retry configuration (default: enabled)
  • enabled (bool/string): Enable/disable retry (default: true, can be set to "false" string to disable)
  • initial_interval (duration): Initial retry interval (default: 5s)
  • max_interval (duration): Maximum retry interval (default: 30s)
  • max_elapsed_time (duration): Maximum total time for all retries (default: 1m)
• http.tls_config (object, optional): TLS configuration
  • cert_file (string): Client certificate file path
  • key_file (string): Client private key file path
  • ca_file (string): CA certificate file path
  • server_name (string): Server name for certificate validation
  • insecure_skip_verify (bool): Skip TLS verification

gRPC Exporter:

• grpc.endpoint (string, required): Collector gRPC endpoint (host:port)
• grpc.timeout (duration, optional): Request timeout
• grpc.insecure (bool, optional): Skip TLS certificate verification
• grpc.compression (string/bool/int, optional): Compression setting (same as HTTP compression)
• grpc.reconnection_period (duration, optional): Reconnection interval after connection loss
• grpc.header (map[string]string, optional): Custom gRPC metadata
• grpc.retry (object/string, optional): Retry configuration (same structure as HTTP retry)
• grpc.tls_config (object, optional): Same structure as HTTP TLS config
• grpc.service_config (string, optional): gRPC service configuration JSON

Zipkin Exporter:

• zipkin.endpoint (string, required): Full URL to Zipkin spans API endpoint

File Exporter:

• file.path (string, required): File path where traces will be written (JSON format)

Environment Variables

All configuration options can be set via environment variables:

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_MODE=release

# Database
DATABASE_DRIVER=mysql
DATABASE_HOST=localhost
DATABASE_USERNAME=root
DATABASE_PASSWORD=password
DATABASE_SCHEMA=ez_console

# JWT
JWT_SECRET=your-secret
JWT_EXPIRATION=24h

# Logging
LOG_LEVEL=info
LOG_FORMAT=json
LOG_PATH=logs

# Tracing
TRACING_SERVICE_NAME=ez-console

# Tracing HTTP Exporter
TRACING_HTTP_ENDPOINT=localhost:4317
TRACING_HTTP_INSECURE=true
TRACING_HTTP_TIMEOUT=30s
TRACING_HTTP_COMPRESSION=gzip
TRACING_HTTP_URL_PATH=/v1/traces
TRACING_HTTP_RETRY={"enabled":true,"initial_interval":"5s","max_interval":"30s","max_elapsed_time":"1m"}

# Tracing gRPC Exporter
TRACING_GRPC_ENDPOINT=localhost:4318
TRACING_GRPC_INSECURE=false
TRACING_GRPC_TIMEOUT=30s
TRACING_GRPC_COMPRESSION=gzip
TRACING_GRPC_RECONNECTION_PERIOD=5s
TRACING_GRPC_SERVICE_CONFIG=""
TRACING_GRPC_RETRY={"enabled":true,"initial_interval":"5s","max_interval":"30s","max_elapsed_time":"1m"}

# Tracing Zipkin Exporter
TRACING_ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans

# Tracing File Exporter
TRACING_FILE_PATH=traces.json

Configuration Precedence

1. Command-line flags (highest priority)
2. Environment variables
3. Configuration file (lowest priority)

Complete Example

# Global
global:
  encrypt_key: "your-32-byte-encryption-key-here"

# Server
server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"
  read_timeout: "10s"
  write_timeout: "10s"
  shutdown_timeout: "10s"
  file_upload_path: "./uploads"
  max_upload_size: 10485760

# Database
database:
  driver: "mysql"
  host: "localhost"
  port: 3306
  username: "root"
  password: "secure-password"
  schema: "ez_console"
  charset: "utf8mb4"
  collation: "utf8mb4_unicode_ci"
  max_open_connections: 100
  max_idle_connections: 10
  max_connection_life_time: "30s"
  table_prefix: "t_"
  slow_threshold: "3s"

# JWT
jwt:
  secret: "your-jwt-secret"
  expiration: "24h"

# Logging
log:
  level: "info"
  format: "json"
  path: "logs"

# OAuth
oauth:
  enabled: true
  providers:
    - name: "google"
      display_name: "Google"
      client_id: "your-client-id"
      client_secret: "your-client-secret"
      auth_url: "https://accounts.google.com/o/oauth2/v2/auth"
      token_url: "https://oauth2.googleapis.com/token"
      user_info_url: "https://www.googleapis.com/oauth2/v2/userinfo"
      redirect_url: "http://localhost:5173/login?provider=google"

# Cache
cache:
  size: 1000

Related Topics

• CLI Commands - Command-line options
• Configuration Guide - Configuration guide

---

Need help? Ask in GitHub Discussions.