Tigase XMPP Server on Ubuntu 24.04 on Azure User Guide

Overview

Tigase XMPP Server is a scalable, extensible XMPP (Jabber) messaging server written in Java. It handles client-to-server (c2s) and server-to-server (s2s) connections, presence, one-to-one and multi-user chat (MUC), publish-subscribe (PubSub) and message archiving, and speaks XMPP over TCP, BOSH and WebSocket. The cloudimg image installs Tigase 8.4.2 on OpenJDK 17 at /opt/tigase, runs it as a dedicated tigase system user, uses the embedded Apache Derby database (no separate database server to run), tunes the JVM heap to fit a Standard_B2s VM, and generates a unique administrator account and password on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• Tigase XMPP Server 8.4.2 on OpenJDK 17 at /opt/tigase, run as the dedicated tigase system user by tigase.service
• The embedded Apache Derby database at /var/lib/tigase/tigasedb — a single, self-contained node with no separate database process
• XMPP listeners: c2s 5222 (STARTTLS), legacy-TLS c2s 5223, s2s 5269 (federation), and BOSH/WebSocket 5280
• The Tigase HTTP component on 8080: a browser admin console at /admin, a /dashboard, a REST API at /rest, and the Tigase Web Client at /ui
• A per-VM administrator account (admin@<domain>) with a random password generated at first boot, in a root-only credentials file
• In-band account registration disabled by default (the server is not an open account relay)
• JVM heap tuned (-Xms512m -Xmx1024m) to fit Standard_B2s (2 vCPU / 4 GiB) with no swap
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is the recommended size for a single node; scale up for more concurrent sessions. NSG inbound: allow 22/tcp from your management network, 8080/tcp for the web console (front with TLS for public exposure — see Setting a production domain and TLS), and the XMPP ports your clients and peers use: 5222/tcp (c2s) for client connections and 5269/tcp (s2s) if you federate with other XMPP servers.

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Tigase XMPP Server by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size (Standard_B2s); under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22), then after deployment open 8080, 5222 and 5269 on the VM's network security group. Review + create, then Create.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name tigase \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name tigase --port 8080 --priority 1010
az vm open-port --resource-group <your-rg> --name tigase --port 5222 --priority 1020
az vm open-port --resource-group <your-rg> --name tigase --port 5269 --priority 1030

Step 3 — Connect to your VM

ssh azureuser@<public-ip>

Step 4 — Confirm the service is running

systemctl is-active tigase.service

active is reported. The JVM server can take a minute or two to fully start on first boot while it loads the database schema and warms up. Confirm the XMPP and HTTP listeners are bound:

ss -tln | grep -E ':(5222|5223|5269|5280|8080) '

You should see listeners on 5222 (c2s), 5223 (legacy-TLS c2s), 5269 (s2s), 5280 (BOSH/WebSocket) and 8080 (HTTP console).

Step 5 — Retrieve the per-VM administrator credentials

A unique administrator account and password are generated on the first boot of every VM and written to a root-only file. There is no default login.

sudo cat /root/tigase-credentials.txt

This shows TIGASE_DOMAIN (the XMPP virtual host, set to the VM's resolvable address at first boot), TIGASE_ADMIN_JID (admin@<domain>) and TIGASE_ADMIN_PASSWORD. Store the password somewhere safe.

Step 6 — Open the web admin console

Browse to http://<public-ip>:8080/admin and sign in with admin@<domain> and the password from Step 5. The admin console manages the running server — add, modify and delete users, configure virtual-host domains, view statistics, set the message of the day, and run ad-hoc administrative commands.

For example, the Configuration → Add Domain command opens a form to add and configure an XMPP virtual host on the running server:

The console is auth-gated. You can confirm it rejects unauthenticated access and accepts the per-VM administrator:

echo -n 'no credentials -> '; curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/admin/
DOM=$(sudo sed -n 's/^TIGASE_DOMAIN=//p' /root/tigase-credentials.txt)
PW=$(sudo sed -n 's/^TIGASE_ADMIN_PASSWORD=//p' /root/tigase-credentials.txt)
echo -n 'per-VM admin  -> '; curl -s -o /dev/null -w '%{http_code}\n' -u "admin@$DOM:$PW" http://127.0.0.1:8080/admin/

no credentials -> 401 and per-VM admin -> 200.

Step 7 — Verify an XMPP client login

Tigase authenticates XMPP clients over c2s on 5222 using STARTTLS. The image ships a small helper that performs a real c2s SASL PLAIN login, which you can use to confirm the administrator credential authenticates end to end:

DOM=$(sudo sed -n 's/^TIGASE_DOMAIN=//p' /root/tigase-credentials.txt)
PW=$(sudo sed -n 's/^TIGASE_ADMIN_PASSWORD=//p' /root/tigase-credentials.txt)
sudo python3 /usr/local/sbin/tigase-auth-check.py 127.0.0.1 5222 "admin@$DOM" "$PW"

AUTH_OK confirms the credential authenticates over XMPP. A wrong password (for example the upstream setup default tigase) is rejected with AUTH_FAIL — the published default never works on a cloudimg VM.

To connect from a desktop or mobile XMPP client (Gajim, Conversations, Dino, Siskin, …), use the JID admin@<domain>, the password from Step 5, and the server address <public-ip> on port 5222. Because the image uses a self-signed certificate for the virtual host by default, accept the certificate on first connect or install your own (see Setting a production domain and TLS).

Step 8 — The Tigase Web Client

Tigase also ships a browser-based XMPP client at http://<public-ip>:8080/ui. Enter the username admin, set the domain to your <domain>, and enter the password to sign in and chat directly from the browser.

Step 9 — Add user accounts

In-band registration is disabled by default, so you create accounts as the administrator. In the admin console (Step 6), expand USERS → Add user, then enter the new user's JID (someone@<domain>) and a password. Users then sign in with any XMPP client or the Tigase Web Client. All of the server's HTTP surfaces are listed on the landing page at http://<public-ip>:8080/:

Step 10 — Setting a production domain and TLS

XMPP works best with a real DNS domain rather than an IP address. Point a DNS name at your VM, then set it as the virtual host: edit default-virtual-host and the admins list in /opt/tigase/current/etc/config.tdsl, restart with sudo systemctl restart tigase.service, and recreate the admin@<domain> account for the new domain from the admin console. Add the standard XMPP SRV records (_xmpp-client._tcp and _xmpp-server._tcp) so clients and federated peers discover the server, and install a CA-issued certificate for the domain in place of the default self-signed certificate for production use.

Maintenance

• Restart the server: sudo systemctl restart tigase.service
• Server log: /opt/tigase/current/logs/tigase-console.log
• Configuration: /opt/tigase/current/etc/config.tdsl (server), /opt/tigase/current/etc/tigase.conf (JVM options)
• The OS receives automatic security updates via unattended-upgrades. To scale up, resize the VM in the Azure Portal and raise the JVM heap (PRODUCTION_HEAP_SETTINGS) in tigase.conf.

Support

Every cloudimg image is backed by 24/7 support. If you have any questions about Tigase XMPP Server on Azure, contact support@cloudimg.co.uk.