convoy.env.example

# Overrides for config loaded from JSON. Variable names match `envconfig` tags on
# `config.Configuration` (see config/config.go); `envconfig.Process` uses prefix `convoy`.

# --- Core ---
CONVOY_API_VERSION=2025-11-24
CONVOY_ENV=oss
CONVOY_HOST=localhost:5005
CONVOY_ROOT_PATH=
CONVOY_CUSTOM_DOMAIN_SUFFIX=
CONVOY_MAX_RESPONSE_SIZE=50
CONVOY_CONSUMER_POOL_SIZE=100
CONVOY_QUEUE_PROVIDER=redis
CONVOY_INSTANCE_INGEST_RATE=1000
CONVOY_API_RATE_LIMIT=1000
CONVOY_WORKER_EXECUTION_MODE=default
CONVOY_MAX_RETRY_SECONDS=0
CONVOY_ENABLE_FEATURE_FLAG=
CONVOY_ENABLE_PROFILING=false
CONVOY_LICENSE_KEY=
CONVOY_LICENSE_SERVICE_HOST=
CONVOY_LICENSE_SERVICE_VALIDATE_ENDPOINT=
CONVOY_LICENSE_SERVICE_TIMEOUT=0s
CONVOY_LICENSE_SERVICE_RETRY_COUNT=0

# --- HTTP server (tags SSL, PORT, etc.; no CONVOY_ prefix) ---
SSL=false
PORT=5005
WORKER_PORT=5006
AGENT_PORT=5008
INGEST_PORT=5009
SOCKET_PORT=0
DOMAIN_PORT=0
HTTP_PROXY=
CONVOY_SSL_CERT_FILE=
CONVOY_SSL_KEY_FILE=

# --- Database (Postgres) ---
CONVOY_DB_TYPE=postgres
CONVOY_DB_SCHEME=postgres
CONVOY_DB_HOST=localhost
CONVOY_DB_USERNAME=postgres
CONVOY_DB_PASSWORD=postgres
CONVOY_DB_DATABASE=convoy
CONVOY_DB_OPTIONS=sslmode=disable&connect_timeout=30
CONVOY_DB_PORT=5432
CONVOY_DB_DSN=
CONVOY_DB_MAX_OPEN_CONN=0
CONVOY_DB_MAX_IDLE_CONN=0
CONVOY_DB_CONN_MAX_LIFETIME=3600
# JSON array of database objects; only used with read-replica feature where supported
CONVOY_DB_READ_REPLICAS=

# --- Postgres queue provider (only when CONVOY_QUEUE_PROVIDER=postgres) ---
# In this mode Postgres also backs the queue, cache, rate limiter, circuit
# breaker and locks, so it carries traffic that Redis carried before. Size the
# pool against the server: CONVOY_DB_MAX_OPEN_CONN multiplied by the number of
# Convoy processes (server, worker, agent, ingest) must stay comfortably below
# the server's max_connections, or a rolling restart exhausts it. Superuser
# connections also consume the slots reserved by superuser_reserved_connections,
# which can lock an administrator out of the instance entirely.
#
# All values below are optional; unset takes the documented default.
# Jobs coalesced into a single insert.
CONVOY_POSTGRES_QUEUE_BATCH_SIZE=64
# How long a flush window waits to fill, in milliseconds. Lower trades
# throughput for latency. Unset takes the default, so set 1 for the shortest
# supported wait rather than 0.
CONVOY_POSTGRES_QUEUE_BATCH_WAIT_MS=2
# Flush windows in flight at once. Each holds a pool connection for its insert,
# so this must stay below CONVOY_DB_MAX_OPEN_CONN or queue writes starve reads.
CONVOY_POSTGRES_QUEUE_WRITE_CONCURRENCY=8
# How long a claimed job stays owned without a renewal before another consumer
# may take it. Bounds how quickly work is recovered from a worker that died.
# The renewal interval is derived from this, so the two cannot drift.
CONVOY_POSTGRES_QUEUE_LEASE_TIMEOUT_SECONDS=90
# Jobs one dequeue claim may take per round trip. Consumers cap this at the
# worker pool size, so a value above the pool has no effect.
CONVOY_POSTGRES_QUEUE_CLAIM_BATCH_SIZE=64
# How long the consumer sleeps when a claim finds no work, in milliseconds.
# LISTEN/NOTIFY wakes it early, so this is the ceiling on idle pickup latency.
CONVOY_POSTGRES_QUEUE_POLL_IDLE_MS=5
# How long a replica may answer a cache read from its own memory, in
# milliseconds. An invalidation applies immediately on the replica that made it
# and within this window on the others. Set a negative value to disable and send
# every cache read to the database.
CONVOY_POSTGRES_CACHE_LOCAL_READ_TTL_MS=1000
# Cache keys held in memory per replica.
CONVOY_POSTGRES_CACHE_LOCAL_READ_SIZE=10000

# --- Redis ---
CONVOY_REDIS_SCHEME=redis
CONVOY_REDIS_HOST=localhost
CONVOY_REDIS_USERNAME=
CONVOY_REDIS_PASSWORD=
CONVOY_REDIS_DATABASE=
CONVOY_REDIS_PORT=6379
CONVOY_REDIS_CLUSTER_ADDRESSES=
CONVOY_REDIS_SENTINEL_MASTER_NAME=
CONVOY_REDIS_SENTINEL_USERNAME=
CONVOY_REDIS_SENTINEL_PASSWORD=
CONVOY_REDIS_TLS_SKIP_VERIFY=false
CONVOY_REDIS_TLS_CERT_FILE=
CONVOY_REDIS_TLS_KEY_FILE=
CONVOY_REDIS_TLS_CA_CERT_FILE=

# --- Prometheus (queue / Asynq metrics address) ---
CONVOY_PROM_DSN=

# --- Logger ---
CONVOY_LOGGER_LEVEL=error

# --- Auth realms ---
CONVOY_SIGNUP_ENABLED=true
CONVOY_NATIVE_REALM_ENABLED=true
CONVOY_PORTAL_REALM_ENABLED=true
CONVOY_JWT_REALM_ENABLED=true
CONVOY_JWT_SECRET=
CONVOY_JWT_EXPIRY=3600
CONVOY_JWT_REFRESH_SECRET=
CONVOY_JWT_REFRESH_EXPIRY=86400
CONVOY_GOOGLE_OAUTH_ENABLED=false
CONVOY_GOOGLE_OAUTH_CLIENT_ID=
CONVOY_GOOGLE_OAUTH_REDIRECT_URL=
CONVOY_SSO_ENABLED=false
CONVOY_SSO_REDIRECT_URL=
# JSON arrays; file realm for dashboard basic / API key auth
CONVOY_BASIC_AUTH_CONFIG=
CONVOY_API_KEY_CONFIG=

# --- SMTP ---
CONVOY_SMTP_SSL=false
CONVOY_SMTP_PROVIDER=
CONVOY_SMTP_URL=
CONVOY_SMTP_PORT=587
CONVOY_SMTP_USERNAME=
CONVOY_SMTP_PASSWORD=
CONVOY_SMTP_FROM=
CONVOY_SMTP_REPLY_TO=

# --- Tracing ---
CONVOY_TRACER_PROVIDER=
CONVOY_OTEL_SAMPLE_RATE=1
CONVOY_OTEL_COLLECTOR_URL=
CONVOY_OTEL_INSECURE_SKIP_VERIFY=true
CONVOY_OTEL_AUTH_HEADER_NAME=
CONVOY_OTEL_AUTH_HEADER_VALUE=
CONVOY_SENTRY_DSN=
CONVOY_SENTRY_SAMPLE_RATE=0
CONVOY_SENTRY_DEBUG=false
CONVOY_SENTRY_ENVIRONMENT=
CONVOY_DATADOG_AGENT_URL=

# --- Retention (partition drop) & webhook archiving ---
# Partition drop keep window. Legacy: CONVOY_RETENTION_POLICY
CONVOY_RETENTION_PERIOD=720h
# Gate licensed 01:00 partition drop (default true)
CONVOY_RETENTION_ENABLED=true
# Cold-storage archive/export. Legacy: CONVOY_RETENTION_POLICY_ENABLED
CONVOY_WEBHOOK_ARCHIVING_ENABLED=false
CONVOY_BACKUP_INTERVAL=1h
CONVOY_CIRCUIT_BREAKER_SAMPLE_RATE=30
CONVOY_CIRCUIT_BREAKER_ERROR_TIMEOUT=30
CONVOY_CIRCUIT_BREAKER_FAILURE_THRESHOLD=70
CONVOY_CIRCUIT_BREAKER_SUCCESS_THRESHOLD=5
CONVOY_CIRCUIT_BREAKER_MINIMUM_REQUEST_COUNT=10
CONVOY_CIRCUIT_BREAKER_OBSERVABILITY_WINDOW=5
CONVOY_CIRCUIT_BREAKER_CONSECUTIVE_FAILURE_THRESHOLD=10
CONVOY_CIRCUIT_BREAKER_SKIP_SLEEP=false

# --- Storage ---
CONVOY_STORAGE_POLICY_TYPE=on-prem
CONVOY_STORAGE_AWS_PREFIX=
CONVOY_STORAGE_AWS_BUCKET=
CONVOY_STORAGE_AWS_ACCESS_KEY=
CONVOY_STORAGE_AWS_SECRET_KEY=
CONVOY_STORAGE_AWS_REGION=
CONVOY_STORAGE_AWS_SESSION_TOKEN=
CONVOY_STORAGE_AWS_ENDPOINT=
CONVOY_STORAGE_PREM_PATH=

# --- Metrics (Prometheus backend when enabled) ---
CONVOY_METRICS_ENABLED=false
CONVOY_METRICS_BACKEND=prometheus
CONVOY_METRICS_SAMPLE_TIME=5
CONVOY_METRICS_QUERY_TIMEOUT=30
CONVOY_METRICS_MATERIALIZED_VIEW_REFRESH_INTERVAL=2

# --- Pyroscope ---
CONVOY_ENABLE_PYROSCOPE_PROFILING=false
CONVOY_PYROSCOPE_URL=
CONVOY_PYROSCOPE_USERNAME=
CONVOY_PYROSCOPE_PASSWORD=
CONVOY_PYROSCOPE_PROFILE_ID=

# --- Dispatcher outbound (CIDR lists comma-separated for slices) ---
CONVOY_DISPATCHER_INSECURE_SKIP_VERIFY=false
CONVOY_DISPATCHER_ALLOW_LIST=0.0.0.0/0,::/0
CONVOY_DISPATCHER_BLOCK_LIST=127.0.0.0/8,::1/128
CONVOY_DISPATCHER_CACERT_PATH=
CONVOY_DISPATCHER_CACERT_STRING=
CONVOY_DISPATCHER_PING_METHODS=HEAD,GET,POST
CONVOY_DISPATCHER_SKIP_PING_VALIDATION=false

# --- SSO service (Convoy Cloud / Overwatch integration) ---
CONVOY_SSO_SERVICE_HOST=https://overwatch.getconvoy.cloud
CONVOY_SSO_SERVICE_REDIRECT_PATH=/sso/redirect
CONVOY_SSO_SERVICE_TOKEN_PATH=/sso/token
CONVOY_SSO_SERVICE_ADMIN_PORTAL_PATH=/sso/admin-portal
CONVOY_SSO_SERVICE_TIMEOUT=10s
CONVOY_SSO_SERVICE_RETRY_COUNT=3

# --- Billing ---
CONVOY_BILLING_ENABLED=false
CONVOY_BILLING_URL=
CONVOY_BILLING_API_KEY=
CONVOY_BILLING_ORGANISATION_HOST=
CONVOY_PAYMENT_PROVIDER_TYPE=
CONVOY_PAYMENT_PROVIDER_PUBLISHABLE_KEY=

# --- HCP Vault (optional secrets) ---
CONVOY_HCP_CLIENT_ID=
CONVOY_HCP_CLIENT_SECRET=
CONVOY_HCP_ORG_ID=
CONVOY_HCP_PROJECT_ID=
CONVOY_HCP_APP_NAME=
CONVOY_HCP_SECRET_NAME=