prosody-nodejs/docs/QUICKSTART.md

Quick Start Guide

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn

Step 1: Install Dependencies

cd prosody-nodejs
npm install

Step 2: Create Environment File

cp .env.example .env

Edit .env:

SERVER_HOST=localhost
SERVER_PORT=5222
LOG_LEVEL=info
STORAGE_TYPE=memory

Step 3: Start Server

# Development mode (with auto-reload)
npm run dev

# Or production mode
npm start

You should see:

14:23:45 INFO [main] Starting Prosody Node.js XMPP Server...
14:23:45 INFO [config] Configuration loaded successfully
14:23:45 INFO [server] Initializing server components...
14:23:45 INFO [c2s] C2S TLS server listening on 0.0.0.0:5222
14:23:45 INFO [bosh] BOSH server listening on port 5280
14:23:45 INFO [websocket] WebSocket server listening on port 5281
14:23:45 INFO [main] Prosody Node.js is ready to accept connections

Testing with a Client

Using Pidgin

1. Download Pidgin
2. Add account:
   • Protocol: XMPP
   • Username: test
   • Domain: localhost
   • Password: password
3. Advanced tab:
   • Connect port: 5222
   • Connect server: localhost
4. Connect!

Using Gajim

1. Download Gajim
2. Add account:
   • JID: test@localhost
   • Password: password
3. Connect!

Using Node.js Client

const { Client } = require('@xmpp/client');

const client = new Client({
  service: 'xmpp://localhost:5222',
  domain: 'localhost',
  username: 'test',
  password: 'password'
});

client.on('online', (address) => {
  console.log('Connected as', address.toString());
  
  // Send presence
  client.send('<presence/>');
});

client.on('stanza', (stanza) => {
  console.log('Received:', stanza.toString());
});

client.start().catch(console.error);

Basic Configuration

Edit config/default.yaml:

server:
  domain: localhost
  
network:
  c2s:
    enabled: true
    port: 5222
    
virtualHosts:
  - domain: localhost
    enabled: true
    modules:
      - roster
      - saslauth
      - disco
      - presence
      - message

Adding Virtual Hosts

virtualHosts:
  - domain: example.com
    enabled: true
    modules:
      - roster
      - saslauth
      - disco
      
  - domain: conference.example.com
    enabled: true
    modules:
      - muc

Enabling Features

Message Archive Management (MAM)

virtualHosts:
  - domain: localhost
    modules:
      - mam
      
moduleConfig:
  mam:
    maxArchiveSize: 10000

Multi-User Chat (MUC)

virtualHosts:
  - domain: conference.localhost
    modules:
      - muc
      
moduleConfig:
  muc:
    persistentRooms: true

HTTP File Upload

modules:
  global:
    - http_files
    
moduleConfig:
  fileSharing:
    enabled: true
    maxFileSize: 10485760
    uploadPath: ./uploads

Security Setup

Enable TLS

1. Generate certificates:

mkdir -p certs
cd certs

# Self-signed certificate (development only)
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes

2. Configure:

network:
  c2s:
    tls:
      enabled: true
      required: false

TLS_CERT_PATH=./certs/server.crt
TLS_KEY_PATH=./certs/server.key

Enable Rate Limiting

rateLimit:
  enabled: true
  maxPointsPerSecond: 10
  blockDuration: 60

Set Connection Limits

security:
  maxConnectionsPerIP: 5
  connectionTimeout: 60000

Monitoring

View Logs

tail -f logs/prosody-nodejs.log

Enable Debug Logging

LOG_LEVEL=debug npm start

Next Steps

• Read Configuration Guide
• Learn about Module Development
• Check API Documentation
• See Examples

Common Issues

Port Already in Use

Error: listen EADDRINUSE: address already in use :::5222

Solution: Change port in configuration or stop other XMPP server.

Permission Denied

Error: listen EACCES: permission denied 0.0.0.0:5222

Solution: Use port > 1024 or run with sudo (not recommended).

TLS Certificate Error

TLS client error: unable to verify certificate

Solution: Use proper certificates or configure client to accept self-signed.

Getting Help

• Documentation: docs/
• GitHub Issues: Report a bug
• XMPP Chat: prosody-nodejs@conference.example.com