3fc1ac3d12
Jingle A/V (XEP-0166/0167/0176) needs a STUN/TURN server for NAT traversal. Add coturn and advertise it to clients via XEP-0215. - coturn container, host networking (a relay needs its full UDP port range reachable, and Docker NAT hides the peer addresses coturn needs). - mod_turn_external in Prosody to advertise the service and mint time-limited credentials from a shared secret. - Advertise UDP and TCP transports plus turns: on 5349, so clients on UDP-blocking networks can still connect. - Deny relaying to private ranges, so this is not an open proxy into internal services. TURN host is guschin.info rather than turn.guschin.info because only the former is in the certificate SANs and turns: clients validate the name. TURN_HOST/TURN_SECRET go in .env, which is gitignored and set per deployment; TURN_SECRET must match static-auth-secret in turnserver.conf. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
4.6 KiB
Prosody XMPP Server
Dockerized Prosody XMPP server with MySQL backend.
Prerequisites
- Docker and Docker Compose
- External MySQL network:
mysqlgit_mysql_network - Environment variables configuration (see Configuration section)
Configuration
This setup uses environment variables for configuration. Create a .env file in the project root with:
# XMPP Configuration
XMPP_DOMAIN=xmpp.guschin.info
XMPP_USER=mish
XMPP_PASSWORD=your_password
# MySQL Configuration
MYSQL_HOST=mysql
MYSQL_USER=prosody
MYSQL_PASSWORD=your_mysql_password
MYSQL_DATABASE=prosody
Starting the Server
Run from the project directory:
docker-compose up -d
This will:
- Build and start the Prosody container
- Connect to external MySQL network (
mysqlgit_mysql_network) - Wait for MySQL to be ready
- Generate self-signed SSL/TLS certificates (if not present)
- Configure Prosody with MySQL backend
Access Points
| Service | Port | Description |
|---|---|---|
| C2S (Client to Server) | 5222 | XMPP client connections |
| S2S (Server to Server) | 5269 | XMPP federation |
| Component Protocol | 5347 | External components |
| HTTP/BOSH/WebSocket | 5280 | Web-based connections |
| HTTPS | 5281 | Secure web connections |
| STUN/TURN | 3478 (UDP+TCP) | NAT traversal for audio/video calls |
| STUN/TURN over TLS | 5349 (UDP+TCP) | Encrypted TURN (turns:) |
| TURN relay range | 49160-49200 (UDP) | Media relay ports |
Features
- Virtual Host:
xmpp.guschin.info - Multi-User Chat (MUC):
muc.xmpp.guschin.info - Storage: MySQL backend with SQL storage
- Admin User:
admin@guschin.info - Health Checks: Automatic container health monitoring
- Memory Limit: 200M
- Auto-restart: Container restarts unless stopped
Enabled Modules
Core modules: roster, saslauth, tls, dialback, disco, carbons, pep, private, blocking, vcard, version, uptime, time, ping, register, last_activity, admin_adhoc, muc_mam
Data Persistence
Volumes are mounted to persist data:
./data/prosody→/var/lib/prosody./logs/prosody→/var/log/prosody./data/prosody/configuration→/etc/prosody/conf.d
Connecting Clients
Use any XMPP client with:
- Server: xmpp.guschin.info
- Port: 5222
- Username: your configured user
- Domain: xmpp.guschin.info
Audio/Video Calls (Jingle)
Voice and video calls use Jingle (XEP-0166/0167/0176). Prosody only carries the signalling; media flows directly between clients, falling back to a TURN relay when NAT prevents a direct path.
Two pieces make this work:
- coturn (
coturncontainer) — the STUN/TURN server. Runs with host networking because a relay needs its whole UDP port range reachable. mod_turn_externalin Prosody — advertises coturn to clients over XEP-0215 and issues time-limited TURN credentials.
Configuration
TURN_SECRET in .env must match static-auth-secret in
coturn/turnserver.conf. .env is gitignored, so
these values are set per-deployment and not committed:
TURN_HOST=guschin.info
TURN_SECRET=<same value as static-auth-secret>
TURN_HOST is guschin.info, not turn.guschin.info: turns: (TLS) clients
validate the hostname against the certificate, and only guschin.info is in
the current cert's SANs. To use turn.guschin.info instead, reissue the
certificate with that name added and update both TURN_HOST and the
external-ip/cert settings accordingly.
external-ip in turnserver.conf is the server's public address. Update it
if the server IP changes, otherwise coturn advertises relay candidates that
peers cannot reach.
Verifying
Check that Prosody advertises the service and coturn answers:
docker logs coturn # should show listeners on 3478/5349
docker exec prosody-xmpp prosodyctl check config
From a client, place a call between two accounts. Clients that support Jingle audio/video include Conversations (Android), Dino, Gajim, and Monal (iOS). Note that Jingle A/V is client-to-client — both parties need a client that supports it.
Firewall
Ports 3478 and 5349 (both UDP and TCP) plus the UDP relay range 49160-49200
must be reachable from the internet. The host has no local firewall
(iptables INPUT policy is ACCEPT), but any provider-level firewall needs
these opened.
Notes
- TLS encryption is not required by default (configurable in prosody.cfg.lua)
- Self-signed certificates are auto-generated on first run
- The container depends on an external MySQL network named
mysqlgit_mysql_network