References
GoFr Configuration Options
This document lists all the configuration options supported by the GoFr framework. The configurations are grouped by category for better organization.
App
| Name | Description | Default Value | |
|---|---|---|---|
| APP_NAME | Name of the application | gofr-app | |
| APP_ENV | Name of the environment file to use (e.g., stage.env, prod.env, or local.env). | ||
| APP_VERSION | Application version | dev | |
| LOG_LEVEL | Level of verbosity for application logs. Supported values are DEBUG, INFO, NOTICE, WARN, ERROR, FATAL | INFO | |
| REMOTE_LOG_URL | URL to remotely change the log level | ||
| REMOTE_LOG_FETCH_INTERVAL | Time interval (in seconds) to check for remote log level updates | 15 | |
| METRICS_PORT | Port on which the application exposes metrics | 2121 | |
| HTTP_PORT | Port on which the HTTP server listens | 8000 | |
| GRPC_PORT | Port on which the gRPC server listens | 9000 | |
| TRACE_EXPORTER | Tracing exporter to use. Supported values: gofr, zipkin, jaeger, otlp. | ||
| TRACER_HOST | Hostname of the tracing collector. Required if TRACE_EXPORTER is set to zipkin or jaeger. | DEPRECATED | |
| TRACER_PORT | Port of the tracing collector. Required if TRACE_EXPORTER is set to zipkin or jaeger. | 9411 | DEPRECATED |
| TRACER_URL | URL of the trace collector. Required if TRACE_EXPORTER is set to zipkin or jaeger. | ||
| TRACER_RATIO | Refers to the proportion of traces that are exported through sampling. It is optional configuration. By default, this ratio is set to 1. | ||
| TRACER_AUTH_KEY | Authorization header for trace exporter requests. Supported for zipkin, jaeger, otlp. | ||
| TRACER_HEADERS | Custom authentication headers for trace exporter requests in comma-separated key=value format (e.g., "X-Api-Key=secret,Authorization=Bearer token"). Supported for zipkin, jaeger, otlp. Takes priority over TRACER_AUTH_KEY. | ||
| CMD_LOGS_FILE | File to save the logs in case of a CMD application | ||
| SHUTDOWN_GRACE_PERIOD | Timeout duration for server shutdown process | 30s | |
| GOFR_TELEMETRY | Enable telemetry for GoFr framework usage | true | |
| LOG_DISABLE_PROBES | Disable log probes for health checks | false | |
| GRPC_ENABLE_REFLECTION | Enable gRPC server reflection | false |
HTTP
| Name | Description |
|---|---|
| REQUEST_TIMEOUT | Set the request timeouts (in seconds) for HTTP server. |
| CERT_FILE | Set the path to your PEM certificate file for the HTTPS server to establish a secure connection. |
| KEY_FILE | Set the path to your PEM key file for the HTTPS server to establish a secure connection. |
CORS
| Name | Description | Default Value |
|---|---|---|
| ACCESS_CONTROL_ALLOW_ORIGIN | Allowed origin(s) for cross-origin requests. Supports comma-separated values for multiple origins (e.g., https://app.example.com,https://admin.example.com). | * |
| ACCESS_CONTROL_ALLOW_HEADERS | Allowed request headers for cross-origin requests. | Authorization, Content-Type, x-requested-with, origin, true-client-ip, X-Correlation-ID |
| ACCESS_CONTROL_ALLOW_METHODS | Allowed HTTP methods. Automatically set from registered routes if not provided. | |
| ACCESS_CONTROL_ALLOW_CREDENTIALS | Allow credentials (cookies, HTTP authentication) in cross-origin requests. | |
| ACCESS_CONTROL_EXPOSE_HEADERS | Additional headers exposed to the client in cross-origin responses. | |
| ACCESS_CONTROL_MAX_AGE | Maximum time (in seconds) browsers can cache preflight responses. |
Datasource
SQL
| Name | Description | Default Value |
|---|---|---|
| DB_DIALECT | Database dialect. Supported values: mysql, postgres, supabase | |
| DB_HOST | Hostname of the database server. | |
| DB_PORT | Port of the database server. | 3306 |
| DB_USER | Username for the database. | |
| DB_PASSWORD | Password for the database. | |
| DB_NAME | Name of the database to use. | |
| DB_MAX_IDLE_CONNECTION | Number of maximum idle connection. | 2 |
| DB_MAX_OPEN_CONNECTION | Number of maximum connections which can be used with database. | 0 (unlimited) |
| DB_SSL_MODE | TLS/SSL mode for database connections. Supported modes: disable (no TLS), preferred (attempts TLS, falls back to plain), require (enforces TLS, skips validation), skip-verify (enforces TLS, no certificate validation), verify-ca (enforces TLS, validates certificate against CA), verify-full (enforces TLS with full validation including hostname). Currently supported for MySQL/MariaDB and PostgreSQL. | disable |
| DB_TLS_CA_CERT | Path to CA certificate file for TLS connections. Required for verify-ca and verify-full SSL modes. | None |
| DB_TLS_CLIENT_CERT | Path to client certificate file for mutual TLS authentication. | None |
| DB_TLS_CLIENT_KEY | Path to client private key file for mutual TLS authentication. | None |
| DB_REPLICA_HOSTS | Comma-separated list of replica database hosts. Used for read replicas. | None |
| DB_REPLICA_PORTS | Comma-separated list of replica database ports. Used for read replicas. | None |
| DB_REPLICA_USERS | Comma-separated list of replica database users. Used for read replicas. | None |
| DB_REPLICA_PASSWORDS | Comma-separated list of replica database passwords. Used for read replicas. | None |
| DB_REPLICA_MAX_IDLE_CONNECTIONS | Maximum idle connections allowed for a replica | 50 |
| DB_REPLICA_MIN_IDLE_CONNECTIONS | Minimum idle connections for a replica | 10 |
| DB_REPLICA_DEFAULT_IDLE_CONNECTIONS | Idle connections used if no primary setting is provided | 10 |
| DB_REPLICA_MAX_OPEN_CONNECTIONS | Maximum open connections allowed for a replica | 200 |
| DB_REPLICA_MIN_OPEN_CONNECTIONS | Minimum open connections for a replica | 50 |
| DB_REPLICA_DEFAULT_OPEN_CONNECTIONS | Open connections used if no primary setting is provided | 100 |
| DB_CHARSET | The character set for database connection | utf8 |
| SUPABASE_CONNECTION_TYPE | Connection type to Supabase. Supported values: direct, session, transaction | direct |
| SUPABASE_PROJECT_REF | Supabase project reference ID | |
| SUPABASE_REGION | Supabase region for pooled connections | |
| DB_URL | Full PostgreSQL connection string for Supabase (alternative to separate config parameters) |
Redis
| Name | Description | Default Value |
|---|---|---|
| REDIS_HOST | Hostname of the Redis server. | localhost |
| REDIS_PORT | Port of the Redis server. | 6379 |
| REDIS_USER | Username for the Redis server (optional). | "" |
| REDIS_PASSWORD | Password for the Redis server (optional). | "" |
| REDIS_DB | Database number to use for the Redis server. | 0 |
| REDIS_TLS_ENABLED | Enable TLS for Redis connections. | false |
| REDIS_TLS_CA_CERT | Path to the TLS CA certificate file for Redis (or PEM-encoded string). | "" |
| REDIS_TLS_CERT | Path to the TLS certificate file for Redis (or PEM-encoded string). | "" |
| REDIS_TLS_KEY | Path to the TLS key file for Redis (or PEM-encoded string). | "" |
Redis PubSub Configuration:
| Name | Description | Default Value |
|---|---|---|
| REDIS_PUBSUB_DB | Redis database number to use only for Redis Pub/Sub (when PUBSUB_BACKEND=REDIS). Use a different DB than REDIS_DB when running GoFr migrations with Redis Streams mode to avoid gofr_migrations key-type collisions. | Default: 15 (highest default Redis database, 0-15) |
| REDIS_PUBSUB_MODE | Operation mode: pubsub or streams. | streams |
| REDIS_STREAMS_CONSUMER_GROUP | Consumer group name (required for streams mode). | "" |
| REDIS_STREAMS_CONSUMER_NAME | Unique consumer name (optional, auto-generated if empty). | "" |
| REDIS_STREAMS_BLOCK_TIMEOUT | Blocking duration for reading new messages using Redis XREADGROUP. Lower values (1s-2s) provide faster detection but increase CPU usage. Higher values (10s-30s) reduce CPU usage, ideal for batch processing. | 5s |
| REDIS_STREAMS_PEL_RATIO | Ratio of PEL (pending) messages to read vs new messages (0.0-1.0). Controls balance between retry and fresh messages. 0.7 = 70% PEL, 30% new. | 0.7 |
| REDIS_STREAMS_MAXLEN | Maximum length of the stream (approximate). Prevents streams from growing indefinitely. Set to 0 for unlimited. | 0 (unlimited) |
Note: When using GoFr migrations with Streams mode, keep
REDIS_DBandREDIS_PUBSUB_DBseparate (defaults: 0 and 15). ForREDIS_STREAMS_BLOCK_TIMEOUT: use 1s-2s for real-time or 10s-30s for batch processing.
Pub/Sub
| Name | Description | Default Value |
|---|---|---|
| PUBSUB_BACKEND | Pub/Sub message broker backend wired automatically by gofr.New(). Accepted values: kafka, google, mqtt, redis (case-insensitive). Other backends (NATS JetStream, AWS SQS, Azure Event Hub) are wired explicitly via app.AddPubSub(...). |
Kafka
| Name | Description | Default Value |
|---|---|---|
| PUBSUB_BROKER | Comma-separated list of broker addresses | localhost:9092 |
| PARTITION_SIZE | Size of each message partition (in bytes) | 0 |
| PUBSUB_OFFSET | Offset to start consuming messages from. -1 for earliest, 0 for latest. | -1 |
| KAFKA_BATCH_SIZE | Number of messages to batch before sending to Kafka | 1 |
| KAFKA_BATCH_BYTES | Number of bytes to batch before sending to Kafka | 1048576 |
| KAFKA_BATCH_TIMEOUT | Time to wait before sending a batch to Kafka | 100ms |
| CONSUMER_ID | Unique identifier for this consumer | gofr-consumer |
| KAFKA_SECURITY_PROTOCOL | Security protocol used to communicate with Kafka (e.g., PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL) | PLAINTEXT |
| KAFKA_SASL_MECHANISM | SASL mechanism for authentication (e.g. PLAIN, SCRAM-SHA-256, SCRAM-SHA-512) | None |
| KAFKA_SASL_USERNAME | Username for SASL authentication | None |
| KAFKA_SASL_PASSWORD | Password for SASL authentication | None |
| KAFKA_TLS_CERT_FILE | Path to the TLS certificate file | None |
| KAFKA_TLS_KEY_FILE | Path to the TLS key file | None |
| KAFKA_TLS_CA_CERT_FILE | Path to the TLS CA certificate file | None |
| KAFKA_TLS_INSECURE_SKIP_VERIFY | Skip TLS certificate verification | false |
| Name | Description |
|---|---|
| GOOGLE_PROJECT_ID | ID of the Google Cloud project. Required for Google Pub/Sub. |
| GOOGLE_SUBSCRIPTION_NAME | Name of the Google Pub/Sub subscription. Required for Google Pub/Sub. |
MQTT
| Name | Description | Default Value | |
|---|---|---|---|
| MQTT_PORT | Port of the MQTT broker | 1883 | |
| MQTT_MESSAGE_ORDER | Enable guaranteed message order | false | |
| MQTT_PROTOCOL | Communication protocol. Supported values: tcp, ssl. | tcp | |
| MQTT_HOST | Hostname of the MQTT broker | localhost | |
| MQTT_USER | Username for the MQTT broker | ||
| MQTT_PASSWORD | Password for the MQTT broker | ||
| MQTT_CLIENT_ID_SUFFIX | Suffix appended to the client ID | ||
| MQTT_QOS | Quality of Service Level | ||
MQTT_KEEP_ALIVE | Sends regular messages to check the link is active. May not work as expected if handling func is blocking execution | MQTT_RETRIEVE_RETAINED | Retrieve retained messages on subscription |
NATS JetStream
| Name | Description | Default Value |
|---|---|---|
| NATS_SERVER | URL of the NATS server. The NATS driver is wired explicitly via app.AddPubSub(...); this row is a convention only — the actual env-var name is whatever you read from app.Config.Get(...) and pass into nats.Config.Server. | nats://localhost:4222 |
| NATS_CREDS_FILE | File containing the NATS credentials | creds.json |
Related production guides
- 12-Factor Configuration: Env-driven config, secrets, and environment parity — apply 12-factor methodology to the configs documented above.