If you are familiar with the process of cloning a Node.js/Express git repository, you can use abbreviated instructions in the README.md file in the github repository.
This IRC client is functional and mostly stable, but still evolving. New features are still being added from time to time.
In order to you this software it is necessary to install and run a Node.js web server on a Linux system. In general, this will involve the following prerequisite knowledge.
NodeJs: As of irc-hybrid-client v0.2.41, the backend web server requires Node version 16 or greater. Node 18 is currently used for development. Node 18 may be required as minimum version the future.
The application was developed in a virtual machine running Debian-11 with the web server running Node v18. The author deploys it for personal use in a cloud VPS single-core shared cpu droplets with 500MB RAM running Debian 11. It has also run on a RaspberryPi 3 and 4 behind a home network NAT router.
No formal security evaluation has been performed. As a security consideration, it is recommended to run the web server in a non-privileged shell without root access. It does not require a privileged port less than 1024, however you must choose a port not blocked by your browser.
If the server is internet facing, it is recommended to configure the server to use TLS certificates to protect passwords using SSL/TLS encryption.
This HTML, CSS and browser JavaScript was written and debugged using the Chrome web browser running under Linux, and using the mobile Chrome browser on an Apple iPhone. The default Chrome fonts are used. Therefore, Chrome is the recommended browser and other browsers may exhibit minor font and page layout issues.
The IRC interface was primarily developed and tested using the DALnet IRC network. Local testing was performed using ngirc-25 from the Debian apt package. Other IRC servers have not been tested. RFC-2812 "Internet Relay Chat: Client Protocol" was the primary specification reference. Considering this is a limited functionality mobile phone client, not all IRC features have been implemented.
Node.js is a JavaScript interpreter that can execute JavaScript programs from a Linux terminal. It is similar to using python, and it includes a package manager, npm, similar to using pip in python. Some web developers prefer node, because their JavaScript programming knowledge can be used for coding both browser and backend web server using the JavaScript language. You can check if nodejs is installed by typing "node -v" in your terminal. If installed, the version will be displayed. This program requires node v16 or greater. If node is not installed, there are several options:
To install Node.js, one option is to visit the Node.js website at https://nodejs.org/en/ where you can download a tar file and compile node from source. The second alternative is to use pre-compiled binaries for Linux that are available from https://github.com/nodesource/distributions. Both of these include installation instructions. Depending on your version of Linux, "nodejs" and "npm" may be available as system packages in your Linux distribution, but these may be older versions.
The next step is to clone the github repository. Typing the following command will install the repository as a folder in the current working directory. Change directory to that folder.
git clone https://github.com/cotarr/irc-hybrid-client.git cd irc-hybrid-client
This program uses the Express web server. The Express web site is located at https://expressjs.com/. Express various JavaScript dependency libraries will be installed using the npm package manager.
The npm package manager library dependencies are specified in the file "package.json". The dependencies will managed by npm and placed in a folder named "node_modules". Prior to installing dependencies, the environment variable "NODE_ENV" should be set to select which dependencies should be included and how program output should be logged.
Select only 1 of the following 2 options.
# Option 1 Run local to try it out. (development --> log to console) export NODE_ENV=development npm install # Option 2 Typical for server installation, use minified files, log output to files. # ci = clean install export NODE_ENV=production npm ci
It is a good practice to use TLS for both the IRC server connection and the browser. The certificates will provide some verification that you are connecting to the intended server, avoiding a man in the middle interception. TLS will also protect passwords used for IRC servers and NickServ services. This step may be skipped when using a TLS enabled load balancer or network proxy external to the irc-hybrid-client,
Managing TLS certificates is a complex task, mostly beyond the scope of these instructions. However some simple guidance may point your in the right direction.
For the IRC server connection, typically port 6697 for TLS, node uses the openssl and certificates in the Linux operating system, and no special configuration should be required to support TLS, provided that nodejs and your system were compiled with the current version of openssl.
For the browser to connect, as with any webserver, use of TLS requires a registered domain name and server TLS certificates that have been signed by a recognized certificate authority. LetsEncrypt certbot is a simple solution. Debian includes certbot as an apt package. Assuming you have a domain name, the following command would generate a set of certificates good for 90 days. Be sure to switch example.com with your domain name.
# Make sure no other programs are listening on ports 80, 443 # Temporarily open firewall ports 80, 443 sudo certbot certonly --standalone -d abcd.example.com
Since it is recommended to run this program in a non-privileged account using non-privileged ports, it may be necessary to make a copy of privkey.pem and fullchain.pem to a local folder where the web server will have read access. It is NOT recommended to run the IRC client as root, simply for certificate access.
If you are a more experienced user and prefer to generate self signed certificates and install your self signed CA into the browser, that approach would work, but it is beyond the scope of these instructions. However, if your intention is to use a smartphone IRC client, a valid domain name with server certificates generally what a smartphone operating system and browser would expect.
The web server settings and IRC server settings are configured separately. The web server settings are defined before starting the server and can not be changed when the server is running. IRC network settings may be edited in the web browser when the server is running.
Web Server Configuration:
There are two possible methods that may be used to define the web server configuration settings. The settings may be stored as properties in the "credentials.json" file, or the settings may be defined as environment variables or entries in the .env file. Only one method can be used at a time. If the credentials.json file exists, it will be parsed for settings, otherwise the environment variables will be parsed for settings. See: Login Config Instructions
IRC Server Configuration:The first time the web server is started, an empty IRC server list will be created automatically as "servers.json" in the base folder of the repository. Upon the first login to the web page at `/irc/webclient.html`, the browser will be automatically redirected to the server list editor page. The IRC server form includes help instructions describing how to add new IRC servers. Optionally, the IRC server list may be edited manually, see: IRC Config Instructions
It is assumed you are generally familiar with configuration of firewall ports. There are two connections that must cross the firewall, one to the IRC server, and one to the browser.
Firewall Firewall
| |
Browser ------|----- webserver ------|------IRC-server
| |
For the IRC server, the backend web server will establish an outgoing connection request to the IRC server, such as port 6667 non-encrypted or 6697 for TLS encrypted. Once established, this socket is kept open continuously for asynchronous communications with the IRC server. Your firewall should allow outgoing connection to the TCP port listed in the IRC server configuration. In most cases, outbound connections are not restricted, so this may not require any special filter rules.
If your server is running an identd daemon to listen on port 113, this would be outside the scope of these instructions. This is really separate from the IRC client.
The firewall must configure one TCP port for incoming connections from the web browser. This incoming port is used two ways. It is used for standard http GET or POST requests from the browser used to download the web page files and make API requests. The port is also used to establish and maintain a websocket connection so the browser can pass IRC messages asynchronously. One single TCP port is used for both.
If you prefer to use restricted port 443 for your webserver, it would be recommended to place the IRC client on an alternate non-privileged port, then use iptables or nftables firewall rules to exchange port numbers to 443 as packets cross the firewall. This will improve security by keeping the IRC client in a non-privileged account. It would be necessary to temporarily remove these firewall rules when using certbot to renew the TLS certificates.
In summary, one inbound TCP connection and one outbound TCP connection are required to pass the firewall. There should be no other other network connections related to this IRC client.
When running on a multi-user system, review directory or file permissions to properly protect configuration passwords and log files. When the program first starts, if not existing, it will create a "logs" folder with 0o700 (drwx------) permissions. The "credentials.json" and "servers.json" files are recommended to be 0o600 (drw-------).
Since GitHub supports other operating systems like MS Windows as well as others, the file permissions flags may not map perfectly during the git clone operations. It is always a good idea to review permissions after a clone.
When the program first starts, if not existing, a "/logs/" folder will be created automatically. If you have enabled logging, the log files will be written to the /logs folder in the base folder of the repository. Configuration of a custom directory location is not supported in this version.
Since version v0.2.38, the program uses the npm rotating-file-stream middleware to limit size of the HTTP access log and the IRC raw message log. Configuration is explained in the login-config section.
If the program is started with environment variable NODE_ENV=development, all logging will be redirected to the console. In a production situation where NODE_ENV=production, log data is written to files in the log folder. For debugging, it is possible to force logging to the console in production by defining NODE_DEBUG_LOG=1 when starting in the production environment.
This assumes the initial setup configuration in the step 5 has been completed.
The web server will be started from the command line. It will remain in the foreground.
While running in the foreground, the server can be stopped by typing ctrl-C in the terminal.
While in the project directory, start the web server by typing:
node bin/www.mjs
To access the IRC client from your web browser, append the path
There are several ways to run the server unattended in the background. One way is to append an "&" symbol to the end of the command line. An alternative method is to load the "screen" program which allows Linux to run a detached command shell that can be reattached at a later time as a console terminal. There are many other methods to manage servers, such as the NPM package "pm2" that can be installed globally and used to automatically restart the server.
If you are running bash want to capture any console standard or error output while running in the background, you may redirect terminal output to a log file and launch to the program into the background by appending an "&". Attempting this from a script or from cron may require full file pathnames. Systems may vary, but it would look something like this:
/usr/bin/node bin/www.mjs &>> logs/node.log &
Optional:
If running multiple instances of irc-hybrid-client, you have probably assigned a different port number and instanceNumber for each instance of irc-hybrid-client on the same server. It can be useful to assign the instanceNumber to be the same as the port number. This will help identify cookies with servers. When listing running processes with the ps command, different instances can be identified using a custom command line to launch the app.
It is safe to add the instance number to the command line as a command line argument. The irc-hybrid-client program does not accept any command line arguments, so placing the optional argument in the command line will be ignored. This is useful with the 'ps' command when multiple instances of irc-hybrid-client are run on the same server. In this example both the port and instance number are set to 4301. The following command line can be used to launch the program with the optional identifier as a command line argument.
/usr/bin/node bin/www.mjs 4301 &>> logs/node.log &
Using the bash command "ps x" would identify the matching process containing "4301" as in the following:
51910 pts/0 Sl 0:07 /usr/bin/node bin/www.mjs 4301 55240 pts/0 Sl 0:04 /usr/bin/node bin/www.mjs 4312
This section is optional. This repository contains both minified and original un-minified files. The repository can be cloned and deployed "as-is", requiring only editing of the configurations files.
Running minify development tools will concatenate multiple web page files into one HTML, one JavaScript, and one CSS file. It will remove comments and whitespace from the javascript, html and css code. This will significantly reduce the download size of the files and reduce bandwidth used by smartphones.
In the case where the web page files have been edited, you may want to regenerate a new folder containing replacement minified files for the web page. The there is a separate repository for this called irc-hybrid-client-dev-tools. There are complete instructions for use of this utility in the irc-hybrid-client-dev-tools repository.
This upgrade procedure is for the case where the web server consists of a cloned git repository, copied and edited configuration files, and packages installed with npm ci, then the web server can be upgraded by stopping the server, changing to the repository folder and typing the following:
git pull --ff-only npm ci