Skip to content

Commit

Permalink
Config file updated
Browse files Browse the repository at this point in the history
  • Loading branch information
@stkegoul
stkegoul committed Jan 29, 2025
1 parent 92fb9e6 commit a19eb2c
Showing 1 changed file with 77 additions and 79 deletions.
156 changes: 77 additions & 79 deletions advanced/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,6 @@ import NeedHelp from "/snippets/need-help.mdx";

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_`.

<Tip>Use environment variables instead of hardcoding values in the configuration file.</Tip>

<br/>

## Configuration Structure
Expand All @@ -25,26 +23,26 @@ The server configuration module provides a centralized way to define your server
```json
{
"server": {
"ssl": false, // Enable SSL (BLNK_SERVER_SSL)
"secure": false, // Enable secure mode (BLNK_SERVER_SECURE)
"secret_key": "", // Server secret key (BLNK_SERVER_SECRET_KEY)
"domain": "", // SSL domain (BLNK_SERVER_SSL_DOMAIN)
"email": "", // SSL email (BLNK_SERVER_SSL_EMAIL)
"port": "5001" // Server port (BLNK_SERVER_PORT)
"ssl": false,
"secure": false,
"secret_key": "",
"domain": "",
"email": "",
"port": "5001"
}
}
```

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `ssl` | boolean | Controls SSL/TLS encryption for secure communications. When enabled, the server will require HTTPS connections and handle SSL certificate management. |
| `secure` | boolean | Enables enhanced security mode with additional protection mechanisms such as strict HTTP headers, CORS policies, and request validation. |
| `secret_key` | string | Used for session encryption, token signing, and other cryptographic operations. Should be a strong, unique value in production. |
| `domain` | string | Specifies the domain name for SSL certificate configuration and cookie settings. Required when SSL is enabled. |
| `email` | string | Contact email address for SSL certificate registration and notifications. Required for automated SSL certificate management. |
| `port` | string | The network port on which the server listens for incoming connections. |
| **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` |
</Tab>
<Tab title="Security considerations">
1. **SSL Configuration:**
Expand All @@ -70,16 +68,16 @@ The data source configuration establishes the connection between the Blnk server
```json
{
"data_source": {
"dns": "" // Required: Database DNS string (BLNK_DATA_SOURCE_DNS)
"dns": ""
}
}
```

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `dns` | string | The database connection string that specifies the location, credentials, and parameters for connecting to your database. Required for server startup. |
| **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` |

<Tip>The DNS string typically follows this pattern: `[driver]://[username]:[password]@[host]:[port]/[database]`</Tip>
</Tab>
Expand All @@ -99,9 +97,9 @@ The Redis configuration manages the connection to your Redis instance, which is

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `dns` | string | The Redis connection string that specifies the host, port, and authentication details for your Redis instance. Required for Redis functionality. |
| **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` |

<Tip>The DNS string typically follows this pattern: `redis://[[username:]password@]host[:port][/database]`</Tip>
</Tab>
Expand All @@ -114,17 +112,17 @@ The TypeSense configuration manages your connection to the TypeSense search engi
```json
{
"typesense": {
"dns": "" // TypeSense URL (BLNK_TYPESENSE_DNS)
"dns": ""
},
"type_sense_key": "" // TypeSense API key
"type_sense_key": ""
}
```

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `dns` | string | The URL endpoint for your TypeSense server instance. Specifies the host and port for the TypeSense connection. |
| **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. |
</Tab>
</Tabs>
Expand All @@ -136,20 +134,20 @@ The rate limiting configuration helps protect the API from abuse and ensures fai
```json
{
"rate_limit": {
"requests_per_second": null, // RPS limit (BLNK_RATE_LIMIT_RPS)
"burst": null, // Burst limit (BLNK_RATE_LIMIT_BURST)
"cleanup_interval_sec": 10800 // Cleanup interval (BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC)
"requests_per_second": null,
"burst": null,
"cleanup_interval_sec": 10800
}
}
```

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `requests_per_second` | number/null | Maximum number of requests allowed per second per client. When null, no RPS limit is applied. |
| `burst` | number/null | Maximum number of requests allowed to exceed the RPS limit in short bursts. When null, no burst limit is applied. |
| `cleanup_interval_sec` | number | Interval in seconds for cleaning up expired rate limit data. Defaults to 3 hours (10800 seconds). |
| **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` |
</Tab>
</Tabs>

Expand All @@ -160,24 +158,24 @@ The transaction configuration manages how Blnk processes and handles batched ope
```json
{
"transaction": {
"batch_size": 100000, // Batch size (BLNK_TRANSACTION_BATCH_SIZE)
"max_queue_size": 1000, // Max queue size (BLNK_TRANSACTION_MAX_QUEUE_SIZE)
"max_workers": 10, // Max workers (BLNK_TRANSACTION_MAX_WORKERS)
"lock_duration": 1800, // Lock duration (BLNK_TRANSACTION_LOCK_DURATION)
"index_queue_prefix": "transactions" // Index queue prefix (BLNK_TRANSACTION_INDEX_QUEUE_PREFIX)
"batch_size": 100000,
"max_queue_size": 1000,
"max_workers": 10,
"lock_duration": 1800,
"index_queue_prefix": "transactions"
}
}
```

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `batch_size` | number/null | Maximum number of items to process in a single transaction batch. |
| `max_queue_size` | number/null | Maximum number of transactions that can be queued for processing. |
| `max_workers` | number | Maximum number of concurrent workers processing transactions. |
| `lock_duration` | number | Duration for which a transaction lock is held. Format: seconds. |
| `index_queue_prefix` | string | Prefix used for the transaction queue names in the indexing system. |
| **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` |
</Tab>
<Tab title="Best Practices">
1. **Batch Processing:**
Expand All @@ -196,22 +194,22 @@ The reconciliation configuration handles how the reconciliation engine works.
```json
{
"reconciliation": {
"default_strategy": "one_to_one", // Default strategy (BLNK_RECONCILIATION_DEFAULT_STRATEGY)
"progress_interval": 100, // Progress interval (BLNK_RECONCILIATION_PROGRESS_INTERVAL)
"max_retries": 3, // Max retries (BLNK_RECONCILIATION_MAX_RETRIES)
"retry_delay": 5 // Retry delay (BLNK_RECONCILIATION_RETRY_DELAY)
"default_strategy": "one_to_one",
"progress_interval": 100,
"max_retries": 3,
"retry_delay": 5
}
}
```

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `default_strategy` | string | Defines the default matching strategy for reconciliation. Options are `one_to_one`, `one_to_many`, `many_to_one`. |
| `progress_interval` | number | Number of records to process before emitting a progress update. |
| `max_retries` | number | Maximum number of retry attempts for failed reconciliation operations. |
| `retry_delay` | string | Time to wait between retry attempts. Format: seconds. |
| **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` |
</Tab>
<Tab title="Best Practices">
1. **Strategy Selection:**
Expand All @@ -231,24 +229,24 @@ The queue configuration defines the various queues used throughout the server fo
```json
{
"queue": {
"transaction_queue": "new:transaction", // (BLNK_QUEUE_TRANSACTION)
"webhook_queue": "new:webhook", // (BLNK_QUEUE_WEBHOOK)
"index_queue": "new:index", // (BLNK_QUEUE_INDEX)
"inflight_expiry_queue": "new:inflight-expiry", // (BLNK_QUEUE_INFLIGHT_EXPIRY)
"number_of_queues": 20 // (BLNK_QUEUE_NUMBER_OF_QUEUES)
"transaction_queue": "new:transaction",
"webhook_queue": "new:webhook",
"index_queue": "new:index",
"inflight_expiry_queue": "new:inflight-expiry",
"number_of_queues": 20
}
}
```

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `transaction_queue` | string | Queue name for processing transaction operations. |
| `webhook_queue` | string | Queue name for handling webhook event delivery. |
| `index_queue` | string | Queue name for managing search index updates. |
| `inflight_expiry_queue` | string | Queue name for tracking and processing in-flight operation timeouts. |
| `number_of_queues` | number | Total number of queue workers to maintain across all queue types. |
| **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` |
</Tab>
</Tabs>

Expand All @@ -265,7 +263,7 @@ The notification configuration manages external integrations for system notifica
"webhook": {
"url": "",
"headers": {},
"max_retries": 25 // Maximum number of retry attempts for failed webhooks
"max_retries": 25
}
}
}
Expand Down Expand Up @@ -299,14 +297,14 @@ The S3 configuration manages connection settings for Amazon S3 storage service f

<Tabs>
<Tab title="Definitions">
| **Attribute** | **Type** | **Description** |
| :-- | :-- | :-- |
| `backup_dir` | string | Directory path where backups will be stored in S3. |
| `aws_access_key_id` | string | AWS access key ID for authentication. |
| `aws_secret_access_key` | string | AWS secret access key for authentication. |
| `s3_endpoint` | string |Custom endpoint URL for S3-compatible services. Leave empty for default AWS S3. |
| `s3_bucket_name` | string | Name of the S3 bucket to use for storage. |
| `s3_region` | string | AWS region where the S3 bucket is located (e.g., "us-east-1"). |
| **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. | |
| `aws_secret_access_key` | string | AWS secret access key for authentication. | |
| `s3_endpoint` | string |Custom endpoint URL for S3-compatible services. Leave empty for default AWS S3. | |
| `s3_bucket_name` | string | Name of the S3 bucket to use for storage. | |
| `s3_region` | string | AWS region where the S3 bucket is located (e.g., "us-east-1"). | |
</Tab>
<Tab title="Best Practices">
1. **Backup Management:**
Expand Down

0 comments on commit a19eb2c

Please sign in to comment.