Skip to content

Configuration Manual

Jump to bottom
Cytech edited this page Mar 4, 2026 · 2 revisions

Sendium is designed to be highly configurable. Since it currently operates without a traditional relational database, all routing rules, vendor configurations, and API keys are managed dynamically via JSON files and environment variables.

When deploying via Docker or Docker Compose, you can override any of the default Quarkus properties by passing them as environment variables (typically converted to UPPER_CASE_WITH_UNDERSCORES) or by mapping a custom application.properties file.

1. Dynamic Configuration Files (Volumes)

Sendium relies on three core JSON files to manage state and routing. By default, the application looks for these in a conf/ directory. When deploying via Docker, you should mount a local folder containing these files to the container.

  • Vendors Configuration: sms.gateway.smpp.dynamic.config.file.path (Default: conf/vendors-config.json)
  • Routing Rules: sms.gateway.rules.dynamic.config.file.path (Default: conf/routing-rules.json)
  • Message API Keys: sms.gateway.api.keys.config.file.path (Default: conf/api-keys.json)

Example Docker Compose Volume Mount:

volumes:
  - ./my-local-conf-dir:/deployments/conf

2. API Security

While standard messaging API keys are managed in the api-keys.json file, access to the administrative endpoints is secured via a master API key.

  • Property: sms.gateway.api-key.admin
  • Environment Variable: SMS_GATEWAY_API_KEY_ADMIN
  • Default: your-admin-api-key (Crucial: Change this in production!)

3. SMPP Server Settings

Sendium acts as an SMPP server to accept incoming connections from your clients or services.

Property Default Value Description
gateway.smpp.server.enabled true Enables or disables the SMPP server.
gateway.smpp.server.host 0.0.0.0 Binds the server to all network interfaces.
gateway.smpp.server.port 2775 The default port for SMPP traffic.
gateway.smpp.server.max-connections 10 Maximum number of concurrent SMPP sessions allowed.
gateway.smpp.server.default-session-timeout-ms 30000 Timeout for idle SMPP sessions (in milliseconds).

4. Delivery Receipts (DLR) Forwarding

Sendium can forward Delivery Receipts (status updates for your sent SMS) to an external system (e.g., your CRM or billing platform) using Webhooks.

  • Enable/Disable: sms.gateway.dlr.forwarding.enabled (Default: true)
  • Webhook URL: quarkus.rest-client.dlr-forwarding.url
    • Default: https://webhook.site/f3058a12-3ac0-4393-9dc6-c41912ffca2b (Change this to your actual endpoint to receive DLRs).

5. Logging Configuration

Extensive logging is built-in to help you monitor performance and troubleshoot issues. You can control the log level and file outputs using the following environment variables:

General Application Logs

  • QUARKUS_LOG_LEVEL: Sets the global logging level (Default: INFO). Can be set to DEBUG or TRACE for troubleshooting.
  • QUARKUS_LOG_FILE_ENABLE: Set to true to write logs to a file (Default: false).
  • QUARKUS_LOG_FILE_PATH: Path for the main log file (Default: smsg.log).

Component-Specific Logs

Sendium separates SMPP traffic logs for easier debugging. If file logging is enabled:

  • QUARKUS_LOG_FILE_SMPPCLIENT_PATH: Logs for the SMPP Client connections (Default: smppclient.log).
  • QUARKUS_LOG_FILE_SMPPSERVER_PATH: Logs for the SMPP Server connections (Default: smppserver.log).

HTTP Access Logs

HTTP request logging is enabled by default to monitor API traffic.

  • QUARKUS_HTTP_ACCESS_LOG_ENABLE: Enables access logs (Default: true).
  • QUARKUS_HTTP_ACCESS_LOG_DIRECTORY: Directory to store HTTP logs if file logging is enabled.

Clone this wiki locally