Set Up Your Blnk Configuration • Blnk Developer Documentation

Overview

Customise your Blnk server with our robust configuration system. This configuration is set via the blnk.json file or environment variables with the prefix, BLNK_.

Configuration structure

Server configuration

The server configuration module provides a centralized way to define your server’s behavior and security settings..

{
  "server": {
    "ssl": false,                  
    "secure": false,               
    "secret_key": "",          
    "domain": "",              
    "email": "",               
    "port": "5001"             
  }
}

Attribute	Type	Description	Environment variables
`ssl`	boolean	Controls SSL/TLS encryption for secure communications. When enabled, the server will require HTTPS connections and handle SSL certificate management.	`BLNK_SERVER_SSL`
`secure`	boolean	Enables enhanced security mode with additional protection mechanisms such as strict HTTP headers, CORS policies, and request validation.	`BLNK_SERVER_SECURE`
`secret_key`	string	Used for session encryption, token signing, and other cryptographic operations. Should be a strong, unique value in production.	`BLNK_SERVER_SECRET_KEY`
`domain`	string	Specifies the domain name for SSL certificate configuration and cookie settings. Required when SSL is enabled.	`BLNK_SERVER_SSL_DOMAIN`
`email`	string	Contact email address for SSL certificate registration and notifications. Required for automated SSL certificate management.	`BLNK_SERVER_SSL_EMAIL`
`port`	string	The network port on which the server listens for incoming connections.	`BLNK_SERVER_PORT`

Attribute	Type	Description	Environment variables
`ssl`	boolean	Controls SSL/TLS encryption for secure communications. When enabled, the server will require HTTPS connections and handle SSL certificate management.	`BLNK_SERVER_SSL`
`secure`	boolean	Enables enhanced security mode with additional protection mechanisms such as strict HTTP headers, CORS policies, and request validation.	`BLNK_SERVER_SECURE`
`secret_key`	string	Used for session encryption, token signing, and other cryptographic operations. Should be a strong, unique value in production.	`BLNK_SERVER_SECRET_KEY`
`domain`	string	Specifies the domain name for SSL certificate configuration and cookie settings. Required when SSL is enabled.	`BLNK_SERVER_SSL_DOMAIN`
`email`	string	Contact email address for SSL certificate registration and notifications. Required for automated SSL certificate management.	`BLNK_SERVER_SSL_EMAIL`
`port`	string	The network port on which the server listens for incoming connections.	`BLNK_SERVER_PORT`

SSL Configuration:
- Enable SSL in production environments to ensure encrypted data transmission.
- Always enable both ssl and secure in production environments
- Always configure with valid certificates in production.
Secret Key Management:
- Use a strong, randomly generated secret key in production.
- Minimum length of 32 characters recommended.
Domain Configuration:
- Properly configure the domain when using SSL to avoid certificate validation issues.
- Use fully qualified domain names (FQDN).
Port Selection:
- Choose appropriate ports based on your deployment environment and security requirements.
- Consider your firewall rules and network policies.

PII tokenization

This configuration ensures that sensitive data is encrypted and protected during tokenization and detokenization operations.

{
  "tokenization_secret": ""
}

Attribute	Type	Description	Environment variables
`tokenization_secret`	string	Secret key used to secure the tokenization process.	`BLNK_TOKENIZATION_SECRET`

Database configuration

The data source configuration establishes the connection between the Blnk server and your database backend.

{
  "data_source": {
    "dns": ""                      
  }
}

Attribute	Type	Description	Environment variables
`dns`	string	The database connection string that specifies the location, credentials, and parameters for connecting to your database. Required for server startup.	`BLNK_DATA_SOURCE_DNS`

The DNS string typically follows this pattern: [driver]://[username]:[password]@[host]:[port]/[database]

Attribute	Type	Description	Environment variables
`dns`	string	The database connection string that specifies the location, credentials, and parameters for connecting to your database. Required for server startup.	`BLNK_DATA_SOURCE_DNS`

The DNS string typically follows this pattern: [driver]://[username]:[password]@[host]:[port]/[database]

Redis configuration

The Redis configuration manages the connection to your Redis instance, which is commonly used for caching, session storage, and message queuing.

{
  "redis": {
    "dns": "",
    "skip_tls_verify": false
  }
}

Attribute	Type	Description	Environment variables
`dns`	string	The Redis connection string that specifies the host, port, and authentication details for your Redis instance. Required for Redis functionality.	`BLNK_REDIS_DNS`
`skip_tls_verify`	boolean	If true, disables TLS certificate verification for Redis connections. Useful for self-signed or untrusted certificates. Defaults to false.	`BLNK_REDIS_SKIP_TLS_VERIFY`

Attribute	Type	Description	Environment variables
`dns`	string	The Redis connection string that specifies the host, port, and authentication details for your Redis instance. Required for Redis functionality.	`BLNK_REDIS_DNS`
`skip_tls_verify`	boolean	If true, disables TLS certificate verification for Redis connections. Useful for self-signed or untrusted certificates. Defaults to false.	`BLNK_REDIS_SKIP_TLS_VERIFY`

Typesense configuration

The TypeSense configuration manages your connection to the TypeSense search engine, enabling fast and typo-tolerant search functionality in your Blnk server.

{
  "typesense": {
    "dns": ""                         
  },
  "type_sense_key": ""               
}

Attribute	Type	Description	Environment variables
`dns`	string	The URL endpoint for your TypeSense server instance. Specifies the host and port for the TypeSense connection.	`BLNK_TYPESENSE_DNS`
`type_sense_key`	string	The API key used for authenticating requests to your TypeSense instance. Required for secure access to the search engine.	`BLNK_TYPESENSE_KEY`

Attribute	Type	Description	Environment variables
`dns`	string	The URL endpoint for your TypeSense server instance. Specifies the host and port for the TypeSense connection.	`BLNK_TYPESENSE_DNS`
`type_sense_key`	string	The API key used for authenticating requests to your TypeSense instance. Required for secure access to the search engine.	`BLNK_TYPESENSE_KEY`

Rate limiting

The rate limiting configuration helps protect the API from abuse and ensures fair resource allocation.

{
  "rate_limit": {
    "requests_per_second": 1000,     
    "burst": 1000,                   
    "cleanup_interval_sec": 60    
  }
}

Attribute	Type	Description	Environment variables
`requests_per_second`	number/null	Maximum number of requests allowed per second per client. When `null`, no RPS limit is applied.	`BLNK_RATE_LIMIT_RPS`
`burst`	number/null	Maximum number of requests allowed to exceed the RPS limit in short bursts. When `null`, no burst limit is applied.	`BLNK_RATE_LIMIT_BURST`
`cleanup_interval_sec`	number	Interval in seconds for cleaning up expired rate limit data. Defaults to 1 minute.	`BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC`

Attribute	Type	Description	Environment variables
`requests_per_second`	number/null	Maximum number of requests allowed per second per client. When `null`, no RPS limit is applied.	`BLNK_RATE_LIMIT_RPS`
`burst`	number/null	Maximum number of requests allowed to exceed the RPS limit in short bursts. When `null`, no burst limit is applied.	`BLNK_RATE_LIMIT_BURST`
`cleanup_interval_sec`	number	Interval in seconds for cleaning up expired rate limit data. Defaults to 1 minute.	`BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC`

Transaction configuration

The transaction configuration manages how Blnk processes and handles batched operations, controlling throughput and resource utilization.

{
  "transaction": {
    "batch_size": 100000,                
    "max_queue_size": 1000,              
    "max_workers": 10,                   
    "lock_duration": 1800,               
    "index_queue_prefix": "transactions" 
  }
}

Attribute	Type	Description	Environment variables
`batch_size`	number/null	Maximum number of items to process in a single transaction batch.	`BLNK_TRANSACTION_BATCH_SIZE`
`max_queue_size`	number/null	Maximum number of transactions that can be queued for processing.	`BLNK_TRANSACTION_MAX_QUEUE_SIZE`
`max_workers`	number	Maximum number of concurrent workers processing transactions.	`BLNK_TRANSACTION_MAX_WORKERS`
`lock_duration`	number	Duration for which a transaction lock is held. Format: seconds.	`BLNK_TRANSACTION_LOCK_DURATION`
`index_queue_prefix`	string	Prefix used for the transaction queue names in the indexing system.	`BLNK_TRANSACTION_INDEX_QUEUE_PREFIX`

Attribute	Type	Description	Environment variables
`batch_size`	number/null	Maximum number of items to process in a single transaction batch.	`BLNK_TRANSACTION_BATCH_SIZE`
`max_queue_size`	number/null	Maximum number of transactions that can be queued for processing.	`BLNK_TRANSACTION_MAX_QUEUE_SIZE`
`max_workers`	number	Maximum number of concurrent workers processing transactions.	`BLNK_TRANSACTION_MAX_WORKERS`
`lock_duration`	number	Duration for which a transaction lock is held. Format: seconds.	`BLNK_TRANSACTION_LOCK_DURATION`
`index_queue_prefix`	string	Prefix used for the transaction queue names in the indexing system.	`BLNK_TRANSACTION_INDEX_QUEUE_PREFIX`

Batch Processing:
- Adjust batch size based on memory availability.
- Consider data consistency requirements.
Queue Management:
- Set queue size based on expected peak load.
- Monitor queue depth and processing latency.

Reconciliation configuration

The reconciliation configuration handles how the reconciliation engine works.

{
  "reconciliation": {
    "default_strategy": "one_to_one",     
    "progress_interval": 100,             
    "max_retries": 3,                     
    "retry_delay": 5                      
  }
}

Attribute	Type	Description	Environment variables
`default_strategy`	string	Defines the default matching strategy for reconciliation. Options are `one_to_one`, `one_to_many`, `many_to_one`.	`BLNK_RECONCILIATION_DEFAULT_STRATEGY`
`progress_interval`	number	Number of records to process before emitting a progress update.	`BLNK_RECONCILIATION_PROGRESS_INTERVAL`
`max_retries`	number	Maximum number of retry attempts for failed reconciliation operations.	`BLNK_RECONCILIATION_MAX_RETRIES`
`retry_delay`	string	Time to wait between retry attempts. Format: seconds.	`BLNK_RECONCILIATION_RETRY_DELAY`

Attribute	Type	Description	Environment variables
`default_strategy`	string	Defines the default matching strategy for reconciliation. Options are `one_to_one`, `one_to_many`, `many_to_one`.	`BLNK_RECONCILIATION_DEFAULT_STRATEGY`
`progress_interval`	number	Number of records to process before emitting a progress update.	`BLNK_RECONCILIATION_PROGRESS_INTERVAL`
`max_retries`	number	Maximum number of retry attempts for failed reconciliation operations.	`BLNK_RECONCILIATION_MAX_RETRIES`
`retry_delay`	string	Time to wait between retry attempts. Format: seconds.	`BLNK_RECONCILIATION_RETRY_DELAY`

Strategy Selection:
- Choose appropriate strategy based on your data structure.
- Validate data integrity before reconciliation.
- Document matching rules for each strategy.
Performance tuning:
- Adjust progress interval for optimal throughput.
- Monitor memory usage during reconciliation.

Queue configuration

The queue configuration defines the various queues used throughout the server for processing different types of operations asynchronously.

{
  "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": true,
    "max_retry_attempts": 3,
    "monitoring_port": "5004"
  }
}

Attribute	Type	Description	Environment variables
`transaction_queue`	string	Queue name for processing transaction operations.	`BLNK_QUEUE_TRANSACTION`
`webhook_queue`	string	Queue name for handling webhook event delivery.	`BLNK_QUEUE_WEBHOOK`
`index_queue`	string	Queue name for managing search index updates.	`BLNK_QUEUE_INDEX`
`inflight_expiry_queue`	string	Queue name for tracking and processing in-flight operation timeouts.	`BLNK_QUEUE_INFLIGHT_EXPIRY`
`number_of_queues`	number	Total number of queue workers to maintain across all queue types.	`BLNK_QUEUE_NUMBER_OF_QUEUES`
`insufficient_fund_retries`	boolean	Determines whether the ledger should automatically retry transactions that fail due to insufficient funds.	`BLNK_QUEUE_INSUFFICIENT_FUND_RETRIES`
`max_retry_attempts`	number	Specifies the maximum number of retry attempts before the transaction with insufficient funds is rejected.	`BLNK_QUEUE_MAX_RETRY_ATTEMPTS`
`monitoring_port`	string	The network port on which the monitoring server listens for incoming connections.	`BLNK_QUEUE_MONITORING_PORT`

Attribute	Type	Description	Environment variables
`transaction_queue`	string	Queue name for processing transaction operations.	`BLNK_QUEUE_TRANSACTION`
`webhook_queue`	string	Queue name for handling webhook event delivery.	`BLNK_QUEUE_WEBHOOK`
`index_queue`	string	Queue name for managing search index updates.	`BLNK_QUEUE_INDEX`
`inflight_expiry_queue`	string	Queue name for tracking and processing in-flight operation timeouts.	`BLNK_QUEUE_INFLIGHT_EXPIRY`
`number_of_queues`	number	Total number of queue workers to maintain across all queue types.	`BLNK_QUEUE_NUMBER_OF_QUEUES`
`insufficient_fund_retries`	boolean	Determines whether the ledger should automatically retry transactions that fail due to insufficient funds.	`BLNK_QUEUE_INSUFFICIENT_FUND_RETRIES`
`max_retry_attempts`	number	Specifies the maximum number of retry attempts before the transaction with insufficient funds is rejected.	`BLNK_QUEUE_MAX_RETRY_ATTEMPTS`
`monitoring_port`	string	The network port on which the monitoring server listens for incoming connections.	`BLNK_QUEUE_MONITORING_PORT`

Notification configuration

The notification configuration manages external integrations for system notifications, including Slack alerts and custom webhooks.

{
  "notification": {
    "slack": {
      "webhook_url": ""
    },
    "webhook": {
      "url": "",
      "headers": {}     
    }
  }
}

Attribute	Type	Description	Environment variables
`slack.webhook_url`	string	Slack webhook URL for sending notifications to specific channels.	`BLNK_SLACK_WEBHOOK_URL`
`webhook.url`	string	Endpoint URL where webhook notifications will be sent.	`BLNK_WEBHOOK_URL`
`webhook.headers`	object	Custom HTTP headers to be included with webhook requests.	`BLNK_WEBHOOK_HEADERS`

Attribute	Type	Description	Environment variables
`slack.webhook_url`	string	Slack webhook URL for sending notifications to specific channels.	`BLNK_SLACK_WEBHOOK_URL`
`webhook.url`	string	Endpoint URL where webhook notifications will be sent.	`BLNK_WEBHOOK_URL`
`webhook.headers`	object	Custom HTTP headers to be included with webhook requests.	`BLNK_WEBHOOK_HEADERS`

S3 configuration

The S3 configuration manages connection settings for Amazon S3 storage service for system backups and file storage.

{
  "backup_dir": "",                      
  "aws_access_key_id": "",
  "aws_secret_access_key": "",
  "s3_endpoint": "",
  "s3_bucket_name": "",
  "s3_region": ""
}

Attribute	Type	Description	Environment variables
`backup_dir`	string	Directory path where backups will be stored in S3.	`BLNK_BACKUP_DIR`
`aws_access_key_id`	string	AWS access key ID for authentication.	`BLNK_AWS_ACCESS_KEY_ID`
`aws_secret_access_key`	string	AWS secret access key for authentication.	`BLNK_AWS_SECRET_ACCESS_KEY`
`s3_endpoint`	string	Custom endpoint URL for S3-compatible services. Leave empty for default AWS S3.	`BLNK_S3_ENDPOINT`
`s3_bucket_name`	string	Name of the S3 bucket to use for storage.	`BLNK_S3_BUCKET_NAME`
`s3_region`	string	AWS region where the S3 bucket is located (e.g., “us-east-1”).	`BLNK_S3_REGION`

Attribute	Type	Description	Environment variables
`backup_dir`	string	Directory path where backups will be stored in S3.	`BLNK_BACKUP_DIR`
`aws_access_key_id`	string	AWS access key ID for authentication.	`BLNK_AWS_ACCESS_KEY_ID`
`aws_secret_access_key`	string	AWS secret access key for authentication.	`BLNK_AWS_SECRET_ACCESS_KEY`
`s3_endpoint`	string	Custom endpoint URL for S3-compatible services. Leave empty for default AWS S3.	`BLNK_S3_ENDPOINT`
`s3_bucket_name`	string	Name of the S3 bucket to use for storage.	`BLNK_S3_BUCKET_NAME`
`s3_region`	string	AWS region where the S3 bucket is located (e.g., “us-east-1”).	`BLNK_S3_REGION`

Backup Management:
- Structure backup directories by date/type
- Implement backup retention policies
- Monitor backup sizes and storage costs
- Verify backup integrity regularly
Region Selection:
- Choose region closest to your application.
- Account for region-specific pricing.
- Enable cross-region replication if needed
Performance:
- Monitor upload/download speeds.
- Use appropriate storage classes.
- Implement retry logic for operations.

Telemetry

This configuration ensures enables telemetry.

{
  "enable_telemetry": "true"
}

Attribute	Type	Description	Environment variables
`enable_telemetry`	string	Sends data to Jaeger for tracing and monitoring via OTLP. Set to `false` to disable.	`BLNK_ENABLE_TELEMETRY`

Default values & validation

Required fields

Data Source DNS (data_source.dns)
Redis DNS (redis.dns)

Automatic defaults

Project name defaults to “Blnk Server”
Server port defaults to “5001”
TypeSense URL defaults to “http://typesense:8108”
Rate limiting:
- If RPS is set without burst, burst defaults to 2 * RPS
- If burst is set without RPS, RPS defaults to burst / 2
- Cleanup interval defaults to 10800 seconds (3 hours)
Telemetry is enabled by default

Transaction defaults

Batch size: 100,000
Max queue size: 1,000
Max workers: 10
Lock duration: 1800 seconds
Index queue prefix: “transactions”

Reconciliation defaults

Default strategy: “one_to_one”
Progress interval: 100
Max retries: 3
Retry delay: 5 seconds

Queue defaults

Transaction queue: “new:transaction”
Webhook queue: “new:webhook”
Index queue: “new:index”
Inflight expiry queue: “new:inflight-expiry”
Number of queues: 20
Insufficient retries: false

Telemetry defaults

Enable telemetry: true

Configuration loading process

Load configuration from JSON file if present.
Override with environment variables.
Validate required fields.
Apply default values.
Trim whitespace from string values.
Setup rate limiting defaults.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please contact us or join our Discord community.

Getting Started

Ledgers

Ledger Balances

Transactions

Reconciliation

Identities

Metadata

Hooks

Search

Guides

Advanced

Configuring your Blnk server

Overview

Configuration structure

Server configuration

PII tokenization

Database configuration

Redis configuration

Typesense configuration

Rate limiting

Transaction configuration

Reconciliation configuration

Queue configuration

Notification configuration

S3 configuration

Telemetry

Default values & validation

Required fields

Automatic defaults

Transaction defaults

Reconciliation defaults

Queue defaults

Telemetry defaults

Configuration loading process

Need help?

Getting Started

Ledgers

Ledger Balances

Transactions

Reconciliation

Identities

Metadata

Hooks

Search

Guides

Advanced

​Overview

​Configuration structure

​Server configuration

​PII tokenization

​Database configuration

​Redis configuration

​Typesense configuration

​Rate limiting

​Transaction configuration

​Reconciliation configuration

​Queue configuration

​Notification configuration

​S3 configuration

​Telemetry

​Default values & validation

​Required fields

​Automatic defaults

​Transaction defaults

​Reconciliation defaults

​Queue defaults

​Telemetry defaults

​Configuration loading process

​Need help?

Overview

Configuration structure

Server configuration

PII tokenization

Database configuration

Redis configuration

Typesense configuration

Rate limiting

Transaction configuration

Reconciliation configuration

Queue configuration

Notification configuration

S3 configuration

Telemetry

Default values & validation

Required fields

Automatic defaults

Transaction defaults

Reconciliation defaults

Queue defaults

Telemetry defaults

Configuration loading process

Need help?