Overview Carrier is configured entirely through environment variables. All configuration options are prefixed with CARRIER_ and can be set in your deployment manifest, Docker Compose file, or shell environment.
Configuration Categories
SQS Configuration Queue connection and polling settings
Webhook Configuration HTTP endpoint and request settings
Health Check Configuration Worker availability monitoring
Logging Configuration Log output and statistics
SQS Configuration Configure how Carrier connects to and polls messages from AWS SQS.
CARRIER_SQS_ENDPOINT The endpoint for the SQS service.
Examples: Production (us-west-2)
Production (us-east-1)
Local Development
CARRIER_SQS_ENDPOINT = https://sqs.us-west-2.amazonaws.com
CARRIER_SQS_QUEUE_NAME The name of the SQS queue to consume messages from.
Example: CARRIER_SQS_QUEUE_NAME = my-events-queue
CARRIER_SQS_BATCH_SIZE The number of messages each SQS receiver will request from SQS in a single poll.
Valid range: 1 to 10 (AWS SQS maximum)
Example: CARRIER_SQS_BATCH_SIZE = 10
All webhooks are transmitted one message per HTTP request, even when batch size is greater than 1.
CARRIER_SQS_RECEIVERS The number of concurrent SQS receivers requesting messages from SQS.
Example: Each receiver runs in its own goroutine and polls SQS independently. Increase this value to poll more aggressively.
CARRIER_SQS_RECEIVER_WORKERS CARRIER_SQS_RECEIVER_WORKERS
The number of concurrent workers transmitting messages as webhooks for each receiver.
Example: CARRIER_SQS_RECEIVER_WORKERS = 10
A common pattern is to set CARRIER_SQS_BATCH_SIZE and CARRIER_SQS_RECEIVER_WORKERS to the same value. This causes all messages in a batch to be transmitted in parallel HTTP requests.
Webhook Configuration Configure how Carrier sends HTTP POST requests to your application.
CARRIER_WEBHOOK_ENDPOINT CARRIER_WEBHOOK_ENDPOINT
string
default: "http://localhost:9000"
The full URL, including protocol and path, where webhooks will be sent.
Examples: Kubernetes (same pod)
Docker Compose
Custom Path
CARRIER_WEBHOOK_ENDPOINT = http://localhost:9000/webhook
CARRIER_WEBHOOK_REQUEST_TIMEOUT CARRIER_WEBHOOK_REQUEST_TIMEOUT
The timeout for webhook HTTP requests.
Accepts any valid Go duration string (e.g., 30s, 1m, 500ms).
Example: CARRIER_WEBHOOK_REQUEST_TIMEOUT = 30s
CARRIER_WEBHOOK_DEFAULT_CONTENT_TYPE CARRIER_WEBHOOK_DEFAULT_CONTENT_TYPE
string
default: "application/json"
The default value sent in the Content-Type header for all webhook POST requests.
Example: CARRIER_WEBHOOK_DEFAULT_CONTENT_TYPE = application/json
This can be overridden per-message by sending an SQS message attribute named Body.ContentType. See the Dynamic Content-Type documentation for details. CARRIER_WEBHOOK_TLS_INSECURE_SKIP_VERIFY CARRIER_WEBHOOK_TLS_INSECURE_SKIP_VERIFY
When set to true, the webhook transmitter will not validate TLS certificates for HTTPS endpoints.
Example: CARRIER_WEBHOOK_TLS_INSECURE_SKIP_VERIFY = true
Only use this in development or testing environments. Never disable TLS verification in production.
Health Check Configuration Carrier can monitor your worker’s availability and wait for it to be ready before processing messages.
CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINT CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINT
When set, enables health check functionality using the provided endpoint.
Example: CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINT = http://localhost:9000/health
When configured, Carrier will:
Wait for this endpoint to respond successfully before processing messages
Exit if the endpoint becomes unavailable (useful for Kubernetes restarts)
CARRIER_WEBHOOK_HEALTH_CHECK_INTERVAL CARRIER_WEBHOOK_HEALTH_CHECK_INTERVAL
The time interval between webhook health checks.
Example: CARRIER_WEBHOOK_HEALTH_CHECK_INTERVAL = 30s
CARRIER_WEBHOOK_HEALTH_CHECK_TIMEOUT CARRIER_WEBHOOK_HEALTH_CHECK_TIMEOUT
The timeout for health check requests.
Example: CARRIER_WEBHOOK_HEALTH_CHECK_TIMEOUT = 5s
CARRIER_WEBHOOK_OFFLINE_THRESHOLD_COUNT CARRIER_WEBHOOK_OFFLINE_THRESHOLD_COUNT
The number of consecutive failed health checks before the webhook is determined to be offline.
Example: CARRIER_WEBHOOK_OFFLINE_THRESHOLD_COUNT = 3
Logging Configuration Control Carrier’s log output and statistics reporting.
CARRIER_ENABLE_COLORIZED_LOGGING CARRIER_ENABLE_COLORIZED_LOGGING
When set to true, enables colorized log messages for terminal output.
Example: CARRIER_ENABLE_COLORIZED_LOGGING = true
Enable this for local development in Docker Compose. Keep it disabled in production Kubernetes deployments where logs are collected by log aggregation systems.
CARRIER_ENABLE_STAT_LOG When set to true, enables periodic statistics log messages.
Example: CARRIER_ENABLE_STAT_LOG = true
Statistics include:
Number of active goroutines
Memory usage
CARRIER_STAT_LOG_TIMER The interval between statistics log messages.
Example: CARRIER_STAT_LOG_TIMER = 60s
Configuration Examples Development Setup Docker Compose
Shell Export
environment : # Required CARRIER_WEBHOOK_ENDPOINT : http://worker:9000/webhook CARRIER_SQS_ENDPOINT : http://sqs:9324 CARRIER_SQS_QUEUE_NAME : default # Development features CARRIER_ENABLE_COLORIZED_LOGGING : "true" CARRIER_ENABLE_STAT_LOG : "true" CARRIER_STAT_LOG_TIMER : 30s
export CARRIER_WEBHOOK_ENDPOINT = http :// localhost : 9000 / webhook export CARRIER_SQS_ENDPOINT = http :// localhost : 9324 export CARRIER_SQS_QUEUE_NAME = default export CARRIER_ENABLE_COLORIZED_LOGGING = true export CARRIER_ENABLE_STAT_LOG = true
Production Kubernetes apiVersion : v1 kind : ConfigMap metadata : name : carrier-config data : SQS_ENDPOINT : https://sqs.us-west-2.amazonaws.com SQS_QUEUE_NAME : production-events SQS_BATCH_SIZE : "10" SQS_RECEIVERS : "2" SQS_RECEIVER_WORKERS : "10" WEBHOOK_ENDPOINT : http://localhost:9000/webhook WEBHOOK_HEALTH_CHECK_ENDPOINT : http://localhost:9000/health WEBHOOK_REQUEST_TIMEOUT : 60s
env : - name : CARRIER_SQS_ENDPOINT value : https://sqs.us-west-2.amazonaws.com - name : CARRIER_SQS_QUEUE_NAME value : production-events - name : CARRIER_SQS_BATCH_SIZE value : "10" - name : CARRIER_SQS_RECEIVERS value : "2" - name : CARRIER_SQS_RECEIVER_WORKERS value : "10" - name : CARRIER_WEBHOOK_ENDPOINT value : http://localhost:9000/webhook - name : CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINT value : http://localhost:9000/health
High Throughput Optimized for processing many messages quickly:
# SQS Configuration CARRIER_SQS_ENDPOINT = https://sqs.us-west-2.amazonaws.com CARRIER_SQS_QUEUE_NAME = high-volume-queue CARRIER_SQS_BATCH_SIZE = 10 CARRIER_SQS_RECEIVERS = 4 CARRIER_SQS_RECEIVER_WORKERS = 10 # Webhook Configuration CARRIER_WEBHOOK_ENDPOINT = http://localhost:9000/webhook CARRIER_WEBHOOK_REQUEST_TIMEOUT = 30s # Health Checks CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINT = http://localhost:9000/health CARRIER_WEBHOOK_HEALTH_CHECK_INTERVAL = 30s
This configuration:
Runs 4 concurrent receivers
Each receiver fetches 10 messages per poll
Each receiver has 10 workers (40 total concurrent webhook requests)
Processes up to 40 messages in parallel
Low Latency Optimized for processing messages as quickly as possible:
# SQS Configuration CARRIER_SQS_ENDPOINT = https://sqs.us-west-2.amazonaws.com CARRIER_SQS_QUEUE_NAME = low-latency-queue CARRIER_SQS_BATCH_SIZE = 1 CARRIER_SQS_RECEIVERS = 1 CARRIER_SQS_RECEIVER_WORKERS = 1 # Webhook Configuration CARRIER_WEBHOOK_ENDPOINT = http://localhost:9000/webhook CARRIER_WEBHOOK_REQUEST_TIMEOUT = 10s # Health Checks CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINT = http://localhost:9000/health CARRIER_WEBHOOK_HEALTH_CHECK_INTERVAL = 10s
This configuration:
Processes messages one at a time
Minimizes overhead for low-volume queues
Reduces memory footprint
With Health Checks Ensures worker availability before processing:
# SQS Configuration CARRIER_SQS_ENDPOINT = https://sqs.us-west-2.amazonaws.com CARRIER_SQS_QUEUE_NAME = my-queue CARRIER_SQS_BATCH_SIZE = 5 # Webhook Configuration CARRIER_WEBHOOK_ENDPOINT = http://localhost:9000/webhook # Health Check Configuration CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINT = http://localhost:9000/health CARRIER_WEBHOOK_HEALTH_CHECK_INTERVAL = 30s CARRIER_WEBHOOK_HEALTH_CHECK_TIMEOUT = 5s CARRIER_WEBHOOK_OFFLINE_THRESHOLD_COUNT = 3
Environment Variable Source The configuration structure is defined in main.go:23-40:
type Config struct { EnableColorizedLogging bool `default:"false" split_words:"true"` EnableStatLog bool `default:"false" split_words:"true"` SQSBatchSize int `envconfig:"SQS_BATCH_SIZE" default:"1"` SQSEndpoint string `envconfig:"SQS_ENDPOINT" required:"true"` SQSQueueName string `envconfig:"SQS_QUEUE_NAME" required:"true"` SQSReceivers int `envconfig:"SQS_RECEIVERS" default:"1"` SQSReceiverWorkers int `envconfig:"SQS_RECEIVER_WORKERS" default:"1"` StatLogTimer time . Duration `default:"120s" split_words:"true"` WebhookEndpoint string `default:"http://localhost:9000" split_words:"true"` WebhookTLSInsecureSkipVerify bool `envconfig:"WEBHOOK_TLS_INSECURE_SKIP_VERIFY" default:"false"` WebhookDefaultContentType string `default:"application/json" split_words:"true"` WebhookRequestTimeout time . Duration `default:"60s" split_words:"true"` WebhookHealthCheckEndpoint string `split_words:"true"` WebhookOfflineThresholdCount int `default:"5" split_words:"true"` WebhookHealthCheckInterval time . Duration `default:"60s" split_words:"true"` WebhookHealthCheckTimeout time . Duration `default:"10s" split_words:"true"` }
Quick Reference Table Variable Required Default Description CARRIER_SQS_ENDPOINTYes - SQS service endpoint URL CARRIER_SQS_QUEUE_NAMEYes - Name of the SQS queue CARRIER_SQS_BATCH_SIZENo 1Messages per SQS poll (1-10) CARRIER_SQS_RECEIVERSNo 1Concurrent SQS receivers CARRIER_SQS_RECEIVER_WORKERSNo 1Workers per receiver CARRIER_WEBHOOK_ENDPOINTNo http://localhost:9000Webhook destination URL CARRIER_WEBHOOK_REQUEST_TIMEOUTNo 60sWebhook request timeout CARRIER_WEBHOOK_DEFAULT_CONTENT_TYPENo application/jsonDefault Content-Type header CARRIER_WEBHOOK_TLS_INSECURE_SKIP_VERIFYNo falseSkip TLS verification CARRIER_WEBHOOK_HEALTH_CHECK_ENDPOINTNo - Health check endpoint CARRIER_WEBHOOK_HEALTH_CHECK_INTERVALNo 60sHealth check interval CARRIER_WEBHOOK_HEALTH_CHECK_TIMEOUTNo 10sHealth check timeout CARRIER_WEBHOOK_OFFLINE_THRESHOLD_COUNTNo 5Failed checks before offline CARRIER_ENABLE_COLORIZED_LOGGINGNo falseEnable colored logs CARRIER_ENABLE_STAT_LOGNo falseEnable statistics logging CARRIER_STAT_LOG_TIMERNo 120sStatistics log interval
Next Steps
Docker Compose Local deployment guide
Kubernetes Production deployment guide
