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 the Prometheus pull endpoint. Set to 0 to disable it (e.g. push-only serverless).	2121
METRICS_EXPORTER	Enables push-based metrics export alongside the pull endpoint. Supported values: otlp, gcp. Unset (or prometheus) keeps pull-only behavior.
METRICS_URL	Endpoint of the OTLP metrics collector/backend. host:port for gRPC, full URL for HTTP. Required when METRICS_EXPORTER is otlp (gcp defaults to telemetry.googleapis.com:443).
METRICS_PROTOCOL	OTLP transport for pushed metrics. Supported values: grpc, http.	grpc
METRICS_EXPORT_INTERVAL	Interval (in seconds) at which metrics are pushed to the collector/backend.	30
METRICS_TEMPORALITY	OTLP temporality preference. Supported values: cumulative, delta, lowmemory. Use delta for Datadog; cumulative for Prometheus/GMP/Grafana.	cumulative
METRICS_HEADERS	Custom headers for metric export requests in comma-separated key=value format (e.g., "dd-api-key=secret"). Takes priority over METRICS_AUTH_KEY.
METRICS_AUTH_KEY	Authorization header value for metric export requests. Used when METRICS_HEADERS is unset.
METRICS_INSECURE	Disables transport security for the OTLP metrics connection. Set to false for managed backends over TLS. Ignored by the gcp exporter (always TLS).	true
METRICS_CARDINALITY_LIMIT	Per-instrument attribute-set limit, inclusive of the overflow slot: an instrument keeps up to one fewer than this many distinct label sets per collection cycle, and the remaining series collapse into a single otel.metric.overflow series (so a value of n keeps n-1 real label sets). Set 0 or negative for unlimited. When unset, the OpenTelemetry SDK default applies (2000, or OTEL_GO_X_CARDINALITY_LIMIT if set); a set value takes precedence over OTEL_GO_X_CARDINALITY_LIMIT. HTTP metrics give requests that match no route (and unknown methods) at most a quarter of this limit, capped at 500 distinct (path, method, status) label sets; past that they are recorded as `__unmatched__` / `__other__`, so scanner traffic cannot push real routes into the overflow series.	2000
OTEL_RESOURCE_ATTRIBUTES	Standard OpenTelemetry resource attributes, comma-separated key=value. Merged into the resource attached to every exported metric. Required for the gcp exporter outside Google Cloud: its ingest rejects any point whose prometheus_target has no location (e.g. "location=us-central1").
HTTP_PORT	Port on which the HTTP server listens	8000
GRPC_PORT	Port on which the gRPC server listens	9000
MCP_PORT	Port on which the MCP server listens, bound to loopback. Only used when `app.EnableMCP()` is called; a port that cannot be claimed fails startup. Set to `0` to keep tools available in-process while serving no MCP transport. A non-numeric or out-of-range value refuses startup. Note the default collides with Vault's — see MCP.	8200
TRACE_EXPORTER	Tracing exporter to use. Supported values: gofr, zipkin, jaeger, otlp, gcp. `gcp` exports directly to Google Cloud's Telemetry (OTLP) API using Application Default Credentials, and requires the blank import `_ "gofr.dev/pkg/gofr/traces/exporters/gcp"`.
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, jaeger or otlp; optional for gcp, which defaults to `telemetry.googleapis.com:443`. For zipkin, jaeger and otlp an `http://` or `https://` scheme selects the transport, and a schemeless `host:port` is governed by TRACER_INSECURE. For gcp the value must be a schemeless `host:port` — that destination is always TLS on 443, so a scheme is rejected at startup rather than interpreted.
TRACER_INSECURE	Whether a schemeless TRACER_URL (`host:port`) is exported over plaintext. Set to `false` to use TLS with the system root CAs. Ignored when TRACER_URL carries an `http://` or `https://` scheme, which selects the transport itself. Takes precedence over the OTel standard OTEL_EXPORTER_OTLP_INSECURE / OTEL_EXPORTER_OTLP_TRACES_INSECURE. Supported for otlp, jaeger.	true
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. A value that is not a valid number is rejected with an error log and also resolves to 1, so a typo over-samples rather than silently disabling tracing.
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
GOFR_ROUTER	Route matcher for the HTTP server. Set to `trie` to opt into the O(path length) trie index instead of the default linear scan — see Routing Performance. Any other value falls back to `mux`.	mux
LOG_DISABLE_PROBES	Disable log probes for health checks	false
GRPC_ENABLE_REFLECTION	Enable gRPC server reflection	false
HEALTH_CACHE_TTL	How long a health result may be served without re-checking the backends, as a duration (`5s`, `10s`, `1m`). Unset, `0` or `disabled` turns caching off, which is the default: within a TTL a recovered backend still reports DOWN and a failed one still reports UP, so it is a trade to opt into rather than inherit.	disabled
HEALTH_CHECK_TIMEOUT	Upper bound on one round of health checks, as a duration (`2s`). Backends that have not answered by then are left out of the response and the aggregate status is DEGRADED. A check that is still running when the round is abandoned keeps running, so a probe arriving before it finishes reports DEGRADED with no per-dependency detail rather than starting a second round against the same unresponsive backend. Unset or `0` means the round is bounded only by each backend client's own timeout.	disabled

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_DB and REDIS_PUBSUB_DB separate (defaults: 0 and 15). For REDIS_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

Google

Name	Description	Default Value
GOOGLE_PROJECT_ID	ID of the Google Cloud project. Required for Google Pub/Sub.	None
GOOGLE_SUBSCRIPTION_NAME	Name of the Google Pub/Sub subscription. Required for Google Pub/Sub.	None
GOOGLE_MAX_OUTSTANDING_MESSAGES	Max messages the client holds waiting for delivery to the handler, per subscribed topic (the memory/goroutine bound, not the handler concurrency). 0 uses the default; a negative value means no limit.	1000
GOOGLE_MAX_OUTSTANDING_BYTES	Max total size (bytes) of messages held waiting for delivery, per subscribed topic. 0 uses the default; a negative value means no limit.	1000000000
GOOGLE_NUM_GOROUTINES	Number of StreamingPull streams opened by the subscriber, per subscribed topic. It is the stream count, not handler concurrency, and does not raise throughput under GoFr's one-message-at-a-time delivery. 0 or a negative value uses the default.	10

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

12-Factor Configuration: Env-driven config, secrets, and environment parity — apply 12-factor methodology to the configs documented above.