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..
Definitions Security considerations 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.
Attribute Type Description Environment variables tokenization_secret
string Secret key used to secure the tokenization process. BLNK_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.
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.
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
The DNS string typically follows this pattern: redis://[[username:]password@]host[:port][/database]
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
The DNS string typically follows this pattern: redis://[[username:]password@]host[:port][/database]
Typesense configuration
The TypeSense configuration manages your connection to the TypeSense search engine, enabling fast and typo-tolerant search functionality in your Blnk server.
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.
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 3 hours (10800 seconds). 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 3 hours (10800 seconds). BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC
Transaction configuration
The transaction configuration manages how Blnk processes and handles batched operations, controlling throughput and resource utilization.
Definitions Best Practices 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.
Definitions Best Practices 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.
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
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
Notification configuration
The notification configuration manages external integrations for system notifications, including Slack alerts and custom webhooks.
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.
Definitions Best Practices 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.
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
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
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 .