Sign inSign up

navneetlalg/twilio-simulator

By navneetlalg

Updated about 1 year ago

Twilio simulator with virtual phone numbers and SMS messaging capabilities

Image
0

439

navneetlalg/twilio-simulator repository overview

Twilio Simulator

Self-contained image that serves a web UI and REST/WebSocket API for a Twilio-like SMS/webhook simulator. The image bundles:

  • Backend: Node.js/TypeScript (Express 5, Socket.IO)
  • Frontend: React + Vite static bundle served by the backend

Exposed on port 3000 by default.

Pull
docker pull navneetlalg/twilio-simulator:latest
Quick start (using local Postgres)

Use your host Postgres or host.docker.internal on macOS/Windows:

docker run -d --name twilio-simulator -p 3000:3000 \
  -e NODE_ENV=production -e PORT=3000 \
  -e DB_HOST=host.docker.internal -e DB_PORT=5432 \
  -e DB_NAME=twilio_simulator -e DB_USER=postgres -e DB_PASSWORD=password \
  -e DB_SSL=false -e JWT_SECRET=change-me -e CORS_ORIGIN="*" \
  navneetlalg/twilio-simulator:latest

curl -s http://localhost:3000/health | cat
# open UI at http://localhost:3000

# initialize schema (alternative): run app migrations once against your DB
docker run --rm --name twilio-migrate \
  -e NODE_ENV=production \
  -e DB_HOST=host.docker.internal -e DB_PORT=5432 \
  -e DB_NAME=twilio_simulator -e DB_USER=postgres -e DB_PASSWORD=password \
  navneetlalg/twilio-simulator:latest node dist/scripts/migrate.js
Quick start (with sidecar Postgres)
# create isolated network
docker network create ts-net >/dev/null 2>&1 || true

# start Postgres
docker run -d --name ts-db --network ts-net \
  -e POSTGRES_DB=twilio_simulator -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password \
  postgres:17-alpine

# start the simulator
docker run -d --name twilio-simulator --network ts-net -p 3000:3000 \
  -e NODE_ENV=production -e PORT=3000 \
  -e DB_HOST=ts-db -e DB_PORT=5432 \
  -e DB_NAME=twilio_simulator -e DB_USER=postgres -e DB_PASSWORD=password \
  -e DB_SSL=false -e JWT_SECRET=change-me -e CORS_ORIGIN="*" \
  navneetlalg/twilio-simulator:latest

# note: the init-db.sql runs only on first boot of a fresh PG data volume
# to re-run it, remove the PG volume or use a new named volume
docker compose example
services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: twilio_simulator
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d twilio_simulator"]
      interval: 10s
      timeout: 5s
      retries: 5
  app:
    image: navneetlalg/twilio-simulator:latest
    environment:
      NODE_ENV: production
      PORT: 3000
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: twilio_simulator
      DB_USER: postgres
      DB_PASSWORD: password
      DB_SSL: "false"
      JWT_SECRET: change-me
      CORS_ORIGIN: "*"
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy
Environment variables
  • PORT (default: 3000)
  • NODE_ENV (default: development)
  • CORS_ORIGIN (default: "*")
  • JWT_SECRET (default: your-super-secret-jwt-key)
  • JWT_EXPIRES_IN (default: 24h)
  • WEBHOOK_TIMEOUT (default: 5000)
  • WEBHOOK_RETRY_ATTEMPTS (default: 3)
  • DB_HOST (default: localhost)
  • DB_PORT (default: 5432)
  • DB_NAME (default: twilio_simulator)
  • DB_USER (default: postgres)
  • DB_PASSWORD (default: password)
  • DB_SSL (default: false)
Ports
  • 3000/tcp: HTTP API + web UI (health: GET /health)
Notes
  • No volumes are required; state is in Postgres.
  • The image is based on node:22-alpine and runs as a non-root user.
  • The UI is already built into the image and served from /public by Express.
License

MIT

Tag summary

Content type

Image

Digest

sha256:098801355

Size

57.4 MB

Last updated

about 1 year ago

docker pull navneetlalg/twilio-simulator