Skip to main content

smpp-connector — Local Development Setup

Status: populated | Last updated: 2026-04-18

Prerequisites​

ToolVersionInstall
Node.js≥ 20 LTSnvm install 20
pnpm≥ 9npm i -g pnpm
Docker + Docker Compose≥ 24docker.com
nats CLIlatestbrew install nats-io/nats-tools/nats

1. Clone and Install​

git clone https://github.com/ghasitech/sms-gateway.git
cd sms-gateway/services/smpp-connector
pnpm install

2. Start Dependencies (Docker Compose)​

# From repo root — starts all infra dependencies + a mock SMPP server
docker compose -f docker-compose.dev.yml up -d postgres redis nats mock-smpp-server

The mock-smpp-server container runs a lightweight SMPP 3.4 simulator that:

  • Accepts bind_transceiver with any credentials
  • Returns submit_sm_resp ESME_ROK with a random message_id
  • Sends a simulated deliver_sm DLR 5 seconds after each submit_sm
  • Sends enquire_link_resp to heartbeats

The mock SMPP server listens on localhost:2775.

3. Seed the Database​

pnpm db:migrate
# No seed data required; smpp-connector creates records dynamically

4. Mock the operator-management-service API​

In local dev, the credential API is mocked via a WireMock stub included in the Docker Compose setup. It returns fixed test credentials for any operator ID:

{
  "operatorId": "550e8400-e29b-41d4-a716-446655440001",
  "host": "localhost",
  "port": 2775,
  "systemId": "test-system-id",
  "password": "test-password",
  "tpsLimit": 100,
  "bindMode": "TRANSCEIVER",
  "backupOperatorId": null
}

5. Environment Variables​

cp .env.example .env

.env.example:

# PostgreSQL
DATABASE_URL=postgresql://smpp_connector:devpassword@localhost:5432/sms_gateway?schema=smpp

# Redis
REDIS_URL=redis://localhost:6379

# NATS
NATS_URL=nats://localhost:4222

# Operators to manage (comma-separated UUIDs)
OPERATOR_IDS=550e8400-e29b-41d4-a716-446655440001

# operator-management-service URL (WireMock in dev)
OPERATOR_MGMT_URL=http://localhost:8080

# Internal service token (any value in dev)
INTERNAL_SERVICE_TOKEN=dev-token

# Management HTTP port
MGMT_PORT=3001

# Logging
LOG_LEVEL=debug

# TLS disabled in dev
TLS_ENABLED=false

6. Run the Service​

# Development mode with hot reload
pnpm dev

# Production build
pnpm build
pnpm start

7. Test the Full Flow​

# Publish a dispatch command to NATS
nats pub smpp.operator.550e8400-e29b-41d4-a716-446655440001 '{
  "version": "1.0",
  "eventId": "test-event-001",
  "messageId": "00000000-0000-0000-0000-000000000001",
  "to": "+93791234567",
  "from": "GhasiSMS",
  "text": "Hello from Ghasi SMS Gateway",
  "operatorId": "550e8400-e29b-41d4-a716-446655440001",
  "accountId": "00000000-0000-0000-0000-000000000099",
  "messageType": "SMS",
  "encoding": "GSM7",
  "longMessageStrategy": "CSMS",
  "enqueuedAt": "2026-04-18T10:00:00.000Z",
  "expiresAt": "2026-04-21T10:00:00.000Z"
}'

# Watch for DLR event (published ~5s later by mock SMPP server)
nats sub sms.dlr.inbound

# Watch for operator health events
nats sub operator.health

8. Run Tests​

pnpm test:unit
pnpm test:integration
pnpm test:cov