How to install BlaB! WS (server & client)
- Introduction
- Before you begin
- Prerequisites
- Install blabws-server
- Install BlaB! WS (client)
- Apache: Run BlaB! WS with SSL and on ports 80/443
- Nginx: Run BlaB! WS with SSL and on ports 80/443
- Start blabws-server automatically on reboot
- Start & stop blabws-server with a bash script
- Troubleshooting
Introduction
BlaB! WS is a realtime web chat (client & server) based on websockets. Both chat and Admin CP are with responsive design, HTML5 and CSS3 compliant, support all modern browsers (incl. mobile browsers), HiDPI displays ready (no raster images). BlaB! WS is tiny - all that users load with their browsers is less than 150kB (50kB gzipped) in 5 HTTP requests (incl. sounds, emoticons, other images, JS and CSS files) and 95% of this content is cached for further use. Client side is written in PHP, HTML/CSS and JavaScript and using MySQL as a backend. Server side is written in Python and compiled with all dependencies in a single executable file. You do not need Python installed.
top
Before you begin
- Do NOT skip steps. If you are unsure what to do, stop and search for a solution with Google.
- All terminal commands you are supposed to run as root. If you are not root put "sudo" in front of the command.
- When you see CentOS the entry is applicable to CentOS only.
top
Prerequisites
- A Linux based web server with Apache/Nginx, PHP5/PHP7 and MySQL/MariaDB installed and in working state
- Access to that server via SSH as a root user or as a user with sudo privileges
- PHP shell_exec enabled in php.ini (required to start/stop server, alternative method is available)
- Basic knowledge about Linux and some basic terminal skills: running commands, editing files
- If your server is configured to accept SSL connections only (https) you have to enable http connections temporarily (recommended) or skip steps 5 and 6 (from install blabws-server) and after installing BlaB! WS (client) continue with Apache/Nginx: Run BlaB! WS with SSL
- Supported distros: Debian 8 Jessie+ / Ubuntu 16.04+ / CentOS 7+
- CentOS With SELinux in enforcing mode set globally (default on CentOS) you need Apache/Nginx running in permissive mode which many experts consider a vulnerability. You need Apache/Nginx in permissive mode in order to: (1) start blabws-server from Admin CP, (2) start blabws-server on reboot, (3) check blabws-server status from Admin CP, (4) create a config file on install, (5) write a log file, (6) setup a websocket proxy - required to run BlaB! WS on a standard port and with SSL. To enable SELinux permissive mode for Apache/Nginx only run:
# CentOS yum install policycoreutils-python semanage permissive -a httpd_t
top
Install blabws-server
- SSH to your server and install telnet, screen and lsof - these utilities are less than 1mB and available in all repositories. You need telnet to check blabws-server status, screen to run your blabws-server from terminal without leaving an open SSH session and lsof to find the process ID of blabws-server in order to stop it.
# CentOS yum install telnet screen lsof
# Debian / Ubuntu apt install telnet screen lsof
- Run arch to determine whether your system is 32-bit (i686) or 64-bit (x86_64) and download the appropriate version of blabws-server from justblab.com.
# CentOS / Debian / Ubuntu arch
- Extract the content of the zip file and upload it to your server. According to FHS, the proper place to upload blabws-server is
/opt
- your blabws-server executable file should be located in its own directory:/opt/blabws-server/blabws-server
. Alternatively, you can put blabws-server in your own directory -/home/USER/blabws-server/blabws-server
. - Run blabws-server:
# CentOS / Debian / Ubuntu /opt/blabws-server/blabws-server
and you should see this:
# CentOS / Debian / Ubuntu blabws-server listening on PORT 9001 (CTRL+\ to stop) ACCESSKEY=123ABCXYZ PORT=9001 LOGFILE=/dev/null Do not use in production with the default ACCESSKEY
- Do NOT close the terminal window where blabws-server is running and check whether blabws-server accepts incoming requests on port 9001 using any online telnet service - if you can connect on port 9001 then skip step 6 how to open a port in the server firewall, stop blabws-server with CTRL+\ (control and backslash) and continue with installing BlaB! WS (client).
-
Open port 9001 in your firewall
CentOS Open port 9001 (firewall-cmd)
Open a new SSH session to your server (leave blabws-server running) and then open port 9001 with firewall-cmd - the default firewall of CentOS
# CentOS firewall-cmd --get-active-zones
The answer of the above command is most likely public, add port 9001 and reload the firewall:
# CentOS firewall-cmd --zone=public --add-port=9001/tcp --permanent firewall-cmd --reload
Repeat step 5 and if you can connect to blabws-server on port 9001, stop blabws-server with CTRL+\ (control and backslash) and continue with installing BlaB! WS (client).
Ubuntu / Debian Open port 9001 (ufw)
Both Ubuntu and Debian do not have a default firewall installed. If port 9001 is inaccessible it's probably iptables to blame. Open a new SSH session to your server (leave blabws-server running) and then open port 9001 with ufw - a great frontend of iptables for Ubuntu and Debian:
# Ubuntu / Debian apt install ufw ufw allow 9001/tcp ufw status verbose ufw enable
ufw status verbose
displays your open ports. You should have ports 22 (ssh), 80 (http), 443(https) and 9001 open. Be careful with this - if you enable ufw with port 22 closed you'll be unable to SSH to your server. Repeat step 5 and if you can connect to blabws-server on port 9001, stop blabws-server with CTRL+\ (control and backslash) and continue with installing BlaB! WS (client).
top
Install BlaB! WS (client)
- Create a new MySQL/MariaDB database blabws, MySQL/MariaDB user with a password and grant that user all privileges on the database blabws. You can skip this step and use an existing database & user. If you are lost here Adminer is a great one-file PHP tool to manage MySQL/MariaDB databases. (Adminer: users are created from Server » Privileges)
- Download BlaB! WS (client) from justblab.com, unzip the content and upload it to your server under your website root directory.
- CHMOD blabws/config.php to 666 so that PHP is allowed to modify this file.
- Go to YOUR-URL.COM/blabws/index.php with your browser. The install will pop up and check whether your system supports the required MySQLi functions and PHP shell_exec which is used to start and stop blabws-server from the Admin CP. Simply follow the instructions (3 steps only):
- Settings you'll be running blabws-server with: server path, accesskey, port, log file
- Database settings: host, database name, user and password
- Admin account: username, email, password, recovery question & answer
When done, you'll see a link to the Admin CP of BlaB! WS. Start blabws-server: Admin CP » BOARD » SERVER STATUS » TURN ON and then EXIT to go to chat.
top
Apache: Run BlaB! WS with SSL and on ports 80/443
CentOS You need an Apache module called proxy_wstunnel. Open /etc/httpd/conf.modules.d/00-proxy.conf
and look for:
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so
If not found, add the line at the end of the file and save.
Open (or create it if doesn't exist) /etc/httpd/conf.d/wstunnel.conf
and add:
ProxyPass "/MyWsServer/" "ws://localhost:9001/"
save the file, restart Apache (remember to start blabws-server from ACP, it is killed when you restart Apache):
# CentOS
systemctl restart httpd
ACP Settings:
- BlaB! WS Admin CP » Server » Server port: remove 9001 and leave the box empty
- BlaB! WS Admin CP » Server » ProxyPass token: MyWsServer
If Apache is configured with SSL:
- BlaB! WS Admin CP » Server » Protocol: wss
When done you can close port 9001 in your server firewall
Ubuntu / Debian You have to enable an Apache module called proxy_wstunnel with the following command:
# Ubuntu / Debian
a2enmod proxy_wstunnel
Add to the config file of Apache (/etc/apache2/sites-enabled/000-default.conf outside VirtualHosts):
ProxyPass "/MyWsServer/" "ws://localhost:9001/"
save the file, restart Apache (remember to start blabws-server from ACP, it is killed when you restart Apache):
# Ubuntu / Debian
systemctl restart apache2
ACP Settings:
- BlaB! WS Admin CP » Server » Server port: remove 9001 and leave the box empty
- BlaB! WS Admin CP » Server » ProxyPass token: MyWsServer
If Apache is configured with SSL:
- BlaB! WS Admin CP » Server » Protocol: wss
When done you can close port 9001 in your server firewall
Performance issues
The Apache websocket proxy could require a lot of memory (40-60mB per 100 users) compared to the Nginx websocket proxy (1-3mB per 100 users). If you expect many chatters consider using Nginx.
top
Nginx: Run BlaB! WS with SSL and on ports 80/443
Add to the config file of Nginx inside the server block(s):
location /MyWsServer/ {
proxy_pass http://localhost:9001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 600s;
# connection will be closed after 600 seconds of inactivity
}
Save the file, restart Nginx (remember to start blabws-server from ACP, it is killed when you restart Nginx):
# CentOS / Ubuntu / Debian
systemctl restart nginx
ACP Settings:
- BlaB! WS Admin CP » Server » Server port: remove 9001 and leave the box empty
- BlaB! WS Admin CP » Server » ProxyPass token: MyWsServer
If Nginx is configured with SSL:
- BlaB! WS Admin CP » Server » Protocol: wss
When done you can close port 9001 in your server firewall
top
Start blabws-server automatically on reboot
If PHP shell_exec is enabled, you can easily autostart blabws-server on reboot. There is a file blabws-server-autostart.txt in your BlaB! WS directory. Rename it to ANYTHING.php, make sure that you have wget installed and create a new CRON job as a root user or with sudo:
# CentOS / Ubuntu / Debian
@reboot sleep 10; wget http://YOUR_WEBSITE.COM/blabws/ANYTHING.php > /dev/null 2>&1
top
Start & stop blabws-server with a bash script
Use this method only if PHP shell_exec is disabled, or you are running blabws-server on another host.
# blabws-server
blabws-server is off...
Press 1 to run blabws-server (screen session)
Press 2 to run blabws-server (detached screen session)
Press any other key to exit
# blabws-server
blabws-server is on...
Press 1 to attach blabws-server to terminal
Press 2 to kill blabws-server
Press any other key to exit
Under BlaB! WS Admin CP » Server » BASH SCRIPT there is a tool for you to create a bash script that starts, stops and checks blabws-server status from terminal. The script will not run unless you have telnet, screen and lsof installed. Make the script executable before running it (chmod +x).
top
Troubleshooting
The most common problem is when you cannot connect to blabws-server for some reason.
Connecting directly on port 9001
- Make sure that your blabws-server is running: BlaB! WS Admin CP » BOARD » SERVER STATUS or from terminal run as a root user or with sudo
lsof -i :9001 | grep LISTEN
- Make sure that ACCESSKEY passed to blabws-server (from config.php or from blabwscontrols.sh in case you start blabws-server with a bash script) matches the one set under BlaB! WS Admin CP » SERVER » ACCESSKEY
- Make sure that BlaB! WS Admin CP » SERVER » PROTOCOL is set to ws, SERVER PORT is 9001, SERVER URL is correct and PROXYPASS TOKEN is empty.
- Increase WS TOKEN VALIDITY IN SECONDS under BlaB! WS Admin CP » SERVER - set 86500
Connecting via Apache/Nginx websocket proxy
- If you have an old distro (e.g. Ubuntu 14.04, CentOS 6) both Apache and Nginx do not have proper websocket proxies.
- Make sure that your blabws-server is running: BlaB! WS Admin CP » BOARD » SERVER STATUS or from terminal run as a root user or with sudo lsof -i :9001 | grep LISTEN
- Make sure that ACCESSKEY passed to blabws-server (from config.php or from blabwscontrols.sh in case you start blabws-server with a bash script) matches the one set under BlaB! WS Admin CP » SERVER » ACCESSKEY
- Make sure that BlaB! WS Admin CP » SERVER » SERVER PORT is empty, SERVER URL is correct and PROXYPASS TOKEN matches the one set in Apache/Nginx config file.
- Increase WS TOKEN VALIDITY IN SECONDS under BlaB! WS Admin CP » SERVER - set 86500
top
- General
- Home page
- What's New
- Contact Us
- Products
- BlaB!
- BlaB! Plus/Pro
- BlaB! WS
- BlaB! WS Pro
- Members
- Members Area
- My Tickets
Page updated: 2017-12-12