Production deployment

Prerequisites

Docker Desktop with the WSL 2 engine
Telegram TG_API_ID and TG_API_HASH
Strong, unique DB_PASSWORD and JWT_SECRET

Never commit .env or tdlib_data/. Existing Telegram API credentials that have previously appeared in scripts should be rotated in Telegram's developer portal before exposing this service publicly.

Windows setup

Run the following once in an Administrator PowerShell, then restart Windows:

wsl --install --no-distribution

After restart, open Docker Desktop and wait until the Linux engine reports that it is running.

Configure

Copy .env.example to .env and set at least:

NODE_ENV=production
DB_USERNAME=postgres
DB_PASSWORD=<strong-random-password>
DB_DATABASE=telegram_gateway
JWT_SECRET=<at-least-32-random-bytes>
TG_API_ID=<telegram-api-id>
TG_API_HASH=<telegram-api-hash>
CORS_ORIGINS=https://your-control-plane.example

Production uses migrations and keeps TypeORM synchronization disabled.

If Docker build containers cannot reach the default Debian repositories, set DEBIAN_MIRROR and DEBIAN_SECURITY_MIRROR to reachable mirrors. HTTP mirrors can bootstrap older base images that do not yet contain CA certificates; keep all application and credential traffic on HTTPS.

Start

From the project root:

docker compose --env-file .env -f docker/docker-compose.yml up -d --build
docker compose --env-file .env -f docker/docker-compose.yml ps

Readiness and API documentation:

GET http://127.0.0.1:3000/api/admin/ready
GET http://127.0.0.1:3000/api/admin/health
http://127.0.0.1:3000/api/docs

Verify

npm run build
npm test -- --runInBand
npm run test:e2e -- --runInBand
node test/real-readonly-smoke.js

The real smoke test uses the session selected by TG_SESSION_DIR and performs read-only calls only: authorization state, connection, current identity, public chat lookup, and chat listing.

Persistent data

Docker volumes preserve:

PostgreSQL data
Redis data
uploaded files
TDLib authorization/session databases

Back up PostgreSQL and the tdlibdata volume together. Losing tdlibdata requires Telegram account authorization again.

Operational behavior

/health is a liveness check.
/ready returns failure if PostgreSQL or Redis is unavailable.
Telegram workers wait for native TDLib initialization before an account is marked started.
Active account sessions restart automatically after application restart.
Incoming TDLib updates are stored, mapped to webhook events, and delivered through the retry queue.
Webhook, proxy, password, audit, message-job, and admin data are tenant scoped.

2.7 KiB Raw Permalink Blame History