Configuration

Blnk can be configured using a JSON configuration file (blnk.json) or environment variables. This guide covers all available configuration options.

Configuration Methods

Blnk supports two configuration approaches:

JSON File

Create a blnk.json file for structured, version-controlled configuration

Environment Variables

Use BLNK_* prefixed environment variables to override or replace JSON config

Environment variables take precedence over blnk.json settings. This allows you to use a base configuration file and override specific values per environment.

Minimal Configuration

The minimum required configuration includes database and Redis connections:

blnk.json (Minimal)

{
  "data_source": {
    "dns": "postgres://user:password@localhost:5432/blnk?sslmode=disable"
  },
  "redis": {
    "dns": "localhost:6379"
  }
}

Blnk will use sensible defaults for all other settings.

Complete Configuration Reference

Here’s a complete configuration file with all available options:

blnk.json (Complete)

{
  "project_name": "Blnk Server",
  
  "server": {
    "port": "5001",
    "ssl": false,
    "domain": "example.com",
    "ssl_email": "[email protected]",
    "cert_storage_path": "/etc/letsencrypt",
    "secure": true,
    "secret_key": "your-secret-key-for-secure-mode"
  },
  
  "data_source": {
    "dns": "postgres://user:password@localhost:5432/blnk?sslmode=disable",
    "max_open_conns": 25,
    "max_idle_conns": 10,
    "conn_max_lifetime": 1800000000000,
    "conn_max_idle_time": 300000000000
  },
  
  "redis": {
    "dns": "localhost:6379",
    "skip_tls_verify": false,
    "pool_size": 100,
    "min_idle_conns": 20
  },
  
  "typesense": {
    "dns": "http://localhost:8108"
  },
  
  "type_sense_key": "blnk-api-key",
  
  "transaction": {
    "batch_size": 100000,
    "max_queue_size": 1000,
    "max_workers": 10,
    "lock_duration": 1800000000000,
    "index_queue_prefix": "transactions",
    "enable_queued_checks": false
  },
  
  "reconciliation": {
    "default_strategy": "one_to_one",
    "progress_interval": 100,
    "max_retries": 3,
    "retry_delay": 5000000000
  },
  
  "queue": {
    "transaction_queue": "new:transaction",
    "webhook_queue": "new:webhook",
    "index_queue": "new:index",
    "inflight_expiry_queue": "new:inflight-expiry",
    "number_of_queues": 20,
    "insufficient_fund_retries": false,
    "max_retry_attempts": 3,
    "monitoring_port": "5004",
    "webhook_concurrency": 20
  },
  
  "rate_limit": {
    "requests_per_second": 5000000,
    "burst": 10000000,
    "cleanup_interval_sec": 10800
  },
  
  "notification": {
    "slack": {
      "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
    },
    "webhook": {
      "url": "https://your-app.com/webhook",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  },
  
  "tokenization_secret": "32-character-secret-for-aes256",
  
  "account_number_generation": {
    "enable_auto_generation": true,
    "http_service": {
      "url": "https://your-service.com/generate-account",
      "timeout": 5000,
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  },
  
  "enable_telemetry": true,
  "enable_observability": true,
  
  "backup_dir": "/backups",
  "aws_access_key_id": "your-aws-key",
  "aws_secret_access_key": "your-aws-secret",
  "s3_bucket_name": "blnk-backups",
  "s3_region": "us-east-1",
  "s3_endpoint": "https://s3.amazonaws.com"
}

Configuration Sections

Server Configuration

Controls the API server behavior:

server.port

string

default:"5001"

Port number for the API server

server.ssl

boolean

default:"false"

Enable automatic SSL certificate provisioning via Let’s Encrypt

server.domain

string

Domain name for SSL certificate (required if ssl is true)

server.ssl_email

string

Email for Let’s Encrypt notifications (required if ssl is true)

server.cert_storage_path

string

Path to store SSL certificates

server.secure

boolean

default:"false"

Enable API key authentication for all endpoints

server.secret_key

string

Secret key for signing API keys (required if secure is true)

Environment Variables:

BLNK_SERVER_PORT=5001
BLNK_SERVER_SSL=false
BLNK_SERVER_SSL_DOMAIN=example.com
BLNK_SERVER_SSL_EMAIL=[email protected]
BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY=your-secret

Data Source Configuration

PostgreSQL database connection and pool settings:

data_source.dns

string

required

PostgreSQL connection stringFormat: postgres://user:password@host:port/database?sslmode=disable

data_source.max_open_conns

integer

default:"25"

Maximum number of open database connections

data_source.max_idle_conns

integer

default:"10"

Maximum number of idle connections in the pool

data_source.conn_max_lifetime

duration

default:"30m"

Maximum lifetime of a connection in nanoseconds (1800000000000 = 30 minutes)

data_source.conn_max_idle_time

duration

default:"5m"

Maximum idle time for a connection in nanoseconds (300000000000 = 5 minutes)

Environment Variables:

BLNK_DATA_SOURCE_DNS="postgres://user:pass@localhost:5432/blnk?sslmode=disable"
BLNK_DATABASE_MAX_OPEN_CONNS=25
BLNK_DATABASE_MAX_IDLE_CONNS=10
BLNK_DATABASE_CONN_MAX_LIFETIME=1800000000000
BLNK_DATABASE_CONN_MAX_IDLE_TIME=300000000000

Redis Configuration

Redis connection and pool settings for queues and caching:

redis.dns

string

required

Redis connection stringFormat: host:port or redis://user:password@host:port/db

redis.skip_tls_verify

boolean

default:"false"

Skip TLS certificate verification (useful for self-signed certificates)

redis.pool_size

integer

default:"100"

Maximum number of socket connections

redis.min_idle_conns

integer

default:"20"

Minimum number of idle connections

Environment Variables:

BLNK_REDIS_DNS=localhost:6379
BLNK_REDIS_SKIP_TLS_VERIFY=false
BLNK_REDIS_POOL_SIZE=100
BLNK_REDIS_MIN_IDLE_CONNS=20

Transaction Configuration

Controls transaction processing behavior:

transaction.batch_size

integer

default:"100000"

Maximum number of transactions to process in a single batch

transaction.max_queue_size

integer

default:"1000"

Maximum number of transactions in the processing queue

transaction.max_workers

integer

default:"10"

Number of concurrent workers processing transactions

transaction.lock_duration

duration

default:"30m"

Duration to hold locks on balances during transaction processing (in nanoseconds)

transaction.index_queue_prefix

string

default:"transactions"

Prefix for transaction indexing queues

transaction.enable_queued_checks

boolean

default:"false"

Enable balance checks for queued transactions

Environment Variables:

BLNK_TRANSACTION_BATCH_SIZE=100000
BLNK_TRANSACTION_MAX_QUEUE_SIZE=1000
BLNK_TRANSACTION_MAX_WORKERS=10
BLNK_TRANSACTION_LOCK_DURATION=1800000000000
BLNK_TRANSACTION_ENABLE_QUEUED_CHECKS=false

Reconciliation Configuration

Settings for the reconciliation engine:

reconciliation.default_strategy

string

default:"one_to_one"

Default reconciliation strategy: one_to_one, one_to_many, or many_to_one

reconciliation.progress_interval

integer

default:"100"

Number of records to process before reporting progress

reconciliation.max_retries

integer

default:"3"

Maximum retry attempts for failed reconciliation operations

reconciliation.retry_delay

duration

default:"5s"

Delay between retry attempts in nanoseconds (5000000000 = 5 seconds)

Environment Variables:

BLNK_RECONCILIATION_DEFAULT_STRATEGY=one_to_one
BLNK_RECONCILIATION_PROGRESS_INTERVAL=100
BLNK_RECONCILIATION_MAX_RETRIES=3
BLNK_RECONCILIATION_RETRY_DELAY=5000000000

Queue Configuration

Redis queue settings for background job processing:

queue.transaction_queue

string

default:"new:transaction"

Redis queue name for transaction processing

queue.webhook_queue

string

default:"new:webhook"

Redis queue name for webhook delivery

queue.number_of_queues

integer

default:"20"

Number of parallel processing queues

queue.webhook_concurrency

integer

default:"20"

Number of concurrent webhook delivery workers

queue.monitoring_port

string

default:"5004"

Port for worker monitoring and metrics

Environment Variables:

BLNK_QUEUE_TRANSACTION=new:transaction
BLNK_QUEUE_WEBHOOK=new:webhook
BLNK_QUEUE_NUMBER_OF_QUEUES=20
BLNK_QUEUE_WEBHOOK_CONCURRENCY=20
BLNK_QUEUE_MONITORING_PORT=5004

Rate Limiting

API rate limiting configuration:

rate_limit.requests_per_second

float

default:"5000000"

Maximum requests per second per IP

rate_limit.burst

integer

default:"10000000"

Burst capacity for rate limiter

rate_limit.cleanup_interval_sec

integer

default:"10800"

Cleanup interval for expired rate limit entries (in seconds)

Environment Variables:

BLNK_RATE_LIMIT_RPS=5000000
BLNK_RATE_LIMIT_BURST=10000000
BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC=10800

Identity Tokenization

PII encryption settings:

tokenization_secret

string

32-character secret key for AES-256 encryption of PII data

Must be exactly 32 bytes for AES-256. Keep this secret secure - losing it means you cannot decrypt tokenized data.

Environment Variables:

BLNK_TOKENIZATION_SECRET="32-character-secret-for-aes256"

Telemetry & Observability

enable_telemetry

boolean

default:"false"

Enable usage telemetry reporting

enable_observability

boolean

default:"false"

Enable OpenTelemetry tracing and metrics export

Environment Variables:

BLNK_ENABLE_TELEMETRY=true
BLNK_ENABLE_OBSERVABILITY=true

Deployment Scenarios

Local Development

blnk.json

{
  "project_name": "Blnk Development",
  "data_source": {
    "dns": "postgres://postgres:password@localhost:5432/blnk?sslmode=disable"
  },
  "redis": {
    "dns": "localhost:6379"
  },
  "server": {
    "port": "5001"
  },
  "enable_observability": true
}

Production with Docker Compose

blnk.json

{
  "project_name": "Blnk Production",
  "data_source": {
    "dns": "postgres://postgres:${POSTGRES_PASSWORD}@postgres:5432/blnk?sslmode=require",
    "max_open_conns": 50,
    "max_idle_conns": 25
  },
  "redis": {
    "dns": "redis:6379",
    "pool_size": 200
  },
  "server": {
    "port": "5001",
    "ssl": true,
    "domain": "api.yourdomain.com",
    "ssl_email": "[email protected]",
    "secure": true,
    "secret_key": "${BLNK_SECRET_KEY}"
  },
  "tokenization_secret": "${TOKENIZATION_SECRET}",
  "rate_limit": {
    "requests_per_second": 1000,
    "burst": 2000
  },
  "enable_telemetry": false,
  "enable_observability": true
}

Cloud Deployment (Managed Services)

blnk.json

{
  "project_name": "Blnk Cloud",
  "data_source": {
    "dns": "postgres://user:[email protected]:5432/blnk?sslmode=require",
    "max_open_conns": 100,
    "conn_max_lifetime": 3600000000000
  },
  "redis": {
    "dns": "rediss://elasticache.region.cache.amazonaws.com:6379",
    "skip_tls_verify": false,
    "pool_size": 300
  },
  "server": {
    "port": "5001",
    "secure": true,
    "secret_key": "${BLNK_SECRET_KEY}"
  },
  "transaction": {
    "max_workers": 50,
    "batch_size": 500000
  },
  "queue": {
    "number_of_queues": 50,
    "webhook_concurrency": 100
  },
  "backup_dir": "/mnt/backups",
  "s3_bucket_name": "blnk-backups-prod",
  "s3_region": "us-east-1",
  "enable_observability": true
}

Configuration Best Practices

Use Environment Variables for Secrets

Never commit secrets to version control. Use environment variable substitution:

{
  "data_source": {
    "dns": "postgres://user:${DB_PASSWORD}@host:5432/blnk"
  }
}

Tune Connection Pools

Set database and Redis pool sizes based on your load:

Light load: 10-25 connections
Medium load: 25-100 connections
Heavy load: 100-300 connections

Monitor actual usage and adjust accordingly.

Enable Observability in Production

Always enable observability in production to leverage distributed tracing:

{
  "enable_observability": true
}

Point OTEL_EXPORTER_OTLP_ENDPOINT to your observability backend (Jaeger, Grafana, etc.).

Adjust Worker Counts

Scale workers based on transaction volume:

Low volume (<1000 txn/sec): 10-20 workers
Medium volume (1000-10000 txn/sec): 20-50 workers
High volume (>10000 txn/sec): 50-100+ workers

Validation

Blnk validates configuration on startup. Required fields:

data_source.dns - Database connection is mandatory
redis.dns - Redis connection is mandatory

If validation fails, Blnk will log detailed error messages and exit.

Next Steps

Quick Start

Create your first transaction with your configured instance

API Reference

Explore all available API endpoints

Getting Started

Core Concepts

Guides

Advanced

Deployment

Configuration

Configuration Methods

JSON File

Environment Variables

Minimal Configuration

Complete Configuration Reference

Configuration Sections

Server Configuration

Data Source Configuration

Redis Configuration

Transaction Configuration

Reconciliation Configuration

Queue Configuration

Rate Limiting

Identity Tokenization

Telemetry & Observability

Deployment Scenarios

Local Development

Production with Docker Compose

Cloud Deployment (Managed Services)

Configuration Best Practices

Validation

Next Steps

Quick Start

API Reference

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Advanced

Deployment

​Configuration Methods

JSON File

Environment Variables

​Minimal Configuration

​Complete Configuration Reference

​Configuration Sections

​Server Configuration

​Data Source Configuration

​Redis Configuration

​Transaction Configuration

​Reconciliation Configuration

​Queue Configuration

​Rate Limiting

​Identity Tokenization

​Telemetry & Observability

​Deployment Scenarios

​Local Development

​Production with Docker Compose

​Cloud Deployment (Managed Services)

​Configuration Best Practices

​Validation

​Next Steps

Quick Start

API Reference

Build docs developers (and LLMs) love

Configuration Methods

Minimal Configuration

Complete Configuration Reference

Configuration Sections

Server Configuration

Data Source Configuration

Redis Configuration

Transaction Configuration

Reconciliation Configuration

Queue Configuration

Rate Limiting

Identity Tokenization

Telemetry & Observability

Deployment Scenarios

Local Development

Production with Docker Compose

Cloud Deployment (Managed Services)

Configuration Best Practices

Validation

Next Steps