# 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:

```powershell
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:

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

## Start

From the project root:

```powershell
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

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