How to install BlaB! WS (server & client)

These videos are for reference only and cover Ubuntu server and Apache.

 

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

top

Prerequisites

top

Install blabws-server

  1. 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
  2. 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
  3. 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.
  4. 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 
  5. 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).
  6. 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)

  1. 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)
  2. Download BlaB! WS (client) from justblab.com, unzip the content and upload it to your server under your website root directory.
  3. CHMOD blabws/config.php to 666 so that PHP is allowed to modify this file.
  4. 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:

If Apache is configured with SSL:

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:

If Apache is configured with SSL:

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:

If Nginx is configured with SSL:

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).

The two methods (ACP & terminal) cannot be mixed - when started from ACP, blabws-server process is owned by www-data or nginx, when started from terminal the process is owned by you. Furthermore, blabws-server will be unable to write to a log file created and owned by someone else.

top

Troubleshooting

The most common problem is when you cannot connect to blabws-server for some reason.

Connecting directly on port 9001

Connecting via Apache/Nginx websocket proxy

top


Page updated: 2017-09-09