I am starting a new series of blog posts here about websocket technology and show you how you can use this wonderful technology in your XPage applications. First, I’ll guide you through the installation of the xocket.io plugin on your domino server. Then we’ll secure the server by adding a special WebSocket user and TLS. Later I’ll show you how to build simple WebSocket XPage applications in Domino Designer. I hope you’ll find this series useful and more people will begin using Mark Ambler’s great plugin.
- Basic WebSocket Server Installation Guide for IBM Domino Server
- Setting up the websocket user
- Securing your WebSocket server with TLS
- Your first non-chat websocket app
- Adding server-side listener for persistence
Prerequisite before install
- IBM Domino Server 9.0.1 updated to Fix Pack 5 or higher
- OpenNTF Extension Library
Here are the links to the latest Domino fix packs FP6:
The installations of these packages are beyond the scope of this guide.
Make sure your IBM Admin shows this:
And you have your Extension library features
If you don’t like reading guides, I also created a 19-minute screencast, in which I guide you through the xocket.io plugin installation live.
Creation the websocketupdate.nsf
Download xocket.io from github. After unpacking the contents you will end up with this directory structure.
Open the xpage-applications folder and copy the chat.ntf and the websocket.ntf into your domino/data folder.
Open your Domino Admin Application. Go to Files and create a new application (Ctrl-N). Check the Show advanced templates checkbox and select Eclipse Update Site. Make sure you change Server from Local to your Domino server. Name the new application websocketupdate.nsf:
After the application is created it will open auomatically, if that’s not the case, press F9 in the IBM Domino Admin application and you will see your newly created websocketupdate.nsf file. Double click on it and when it opens click on the purple button Import Local Update Site…. Browse to the downloaded xocket.io folder and look for folder com.tc.websokcet.updatesite. Click on the site.xml file.
After the installation your application should look like this. As of today (07/12/2016) the latest version of xocket.io is 2.0.7:
Creation of the websocket.nsf
Create a new application again in Domino Admin > Files. Name it websocket.nsf. And choose the websocket.ntf template from your domino data folder that you previously copied from the xpage-applications folder.
Creation of the chat.nsf
Create a new application again in Domino Admin > Files. Name it chat.nsf. And choose the chat.ntf template from your domino data folder that you previously copied from the xpage-applications folder. This application will be used to test if the WebSocket server works, and it’s also a great learning tool for your XPage applications using WebSocket.
By now, we have all the necessary files.
Open your notes.ini that is located in your Domino folder and look for the line: OSGI_HTTP_DYNAMIC_BUNDLES=extlibupdate
You might have named your extension library update site something else. Nevertheless, extend this line including websocketupdate.nsf.
Prepend this line of notes.in with two more lines, so it looks like this
Save your notes.ini
This file is located in /Domino/jvm/lib/security
Open java.policy in Notepad and append these three lines to the end of the file
Save the java.policy file.
Make sure you sign all three new applications that you created.
For all three files set these ACL properties (replace Admin User with your user name):
- Default: No Access
- Anonymous: No Access
- Admin User: Manager
Well done, You have just installed the websocket plugin onto your Domino server. Admit it, it was as easy as pie!
Testing the websocket extension
Restart your domino server and examine the startup log messages. It should look something like this:
If you did not get any error messages, then eveything is working
Testing the chat application
Before we test the chat applciation in a browser, we need to edit the application. Open the chat.nsf in Domino Designer, then open the chat.xsp XPage. In the Events choose the beforePageLoad event. It wil look like this:
, "chatapp", "password"
from the end of the third line and save your Xpage. The end result should look like this.
Now open the application in your favorit browser (make sure that if it’s IE, then it’s >10) and log in. If you are not prompted for login, check the ACL of the chat.nsf for the Anonymous user.
Once you have logged in, you should see the CONNECTED message. That means that you have successfully established a websocket connection between your browser and the Domino server. Well done!!
From the chat with combobox, select broadcast, enter a message and click the send button. You should see something like this:
If you examine your Domino server console, you should see no errors, only messages similar to this:
This indicates that you have established a stable websocket connection and also loaded the server side listener successfully.
Congratulations! You have a working websocket server in your Domino server. In the next post, we will make your websocket server safer. It will be even easier than these steps. If you have encountered any problems, please leave a comment. I would also appreciate feedback, if you were successful installing WebSocket on your server following these instrucions.