Skip to content

Installation guide

Jump to bottom
Eric M. edited this page Aug 11, 2025 · 3 revisions

Prerequisites

Xows is not (for now) a standalone application but a Web Client, it therefore needs some prerequisites.

An HTTP(S) Web Server

Or more simply, a Web Hosting space. Since it is a Web Client, it works only inside a browser window as a web page (it needs a web page as "entry point"). Therefore, to run and use it, you need to deploy it on a web server and accessing it through an URL, like any other web site. It however does not require any other thing than proper HTTP access to script and asset files. No need for database nor specific CGI/Php configuration.

A WebSocket-capable XMPP Server

Since it is only a Client that works over WebSocket protocol, you'll have to connect it to an XMPP server that allows WebSocket connection. Majors XMPP service software (Prosody, Ejabberd, etc.) now provides such feature, but they usually needs specific configuration to enable it.

Installation / deployment

The deployment is fairly straightforward, you simply have to put Xows files into your web hosting space, making them accessible like a web site.

Web Portal setup

The web client itself needs an HTML page as "entry point". This page must load application script (JavaScript) files using <script> element within HTML <header>, and have another <script> section where application options are defined and application initialization function is called (to run the application). Examples for such web page are provided here:

Notice that on client browser side, the application will dynamically download then incorporates its assets (interface) within this web page. The HTML page <body> will be filled with application GUI, style sheets will also be loaded and even dynamically generated in part.

The HTML "entry point" web page does not necessarily have to lie aside Xows files, you can put the Xows files within a subfolder. In this case, take care to properly setup scripts path and adjust configuration accordingly to allow application to found asset files. As example, here is how you should modify the provided example index.html page in case you put Xows files within an xows subfolder:

<script src="xows/xows.min.js"></script>
  // Set options
  const options = {
    // Base configuration
    "lib_path"            : "/xows",                                //< Path to XOWS files (relative to HTTP base URL)

XMPP connection configuration

Xows does not (for now) allow final user to choose the XMPP server he want to connect to. This is configured via a global option defined within the HTML entry point:

    // XMPP/Websocket configuration
    "xmpp_url"            : "wss://example.com/xmpp-websocket/",    //< XMPP server Websocket address

Notice that the only required thing is this URL to be accessible from the user browser. It is indeed the user browser that connects to the XMPP server via WebSocket, not your web server.

Clone this wiki locally