Skip to content
A simple NodeJS chat server with a web client
JavaScript CSS HTML
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
classes Let's Encrypt Sep 1, 2017
mail Email fixes: Mar 26, 2017
node_modules Minor Update Jun 1, 2017
web Fixed typo in chat.js Sep 6, 2017
.DS_Store Files Update Jun 2, 2017
.gitignore User Export Sep 1, 2017
LICENSE Message Updates Sep 1, 2017 Removed reference to discontinued server ... Jan 13, 2019
server.js Message Updates Sep 1, 2017


Freech is a simple chat server that comes with a web client. The server side part is a NodeJS app with a MongoDB database. The Freech chat protocol is a simple JSON based protocol that is build on top of the EngineIO WebSocket implementation.

See a sample server here:


Freech is a basic chat application and comes with the following features:

  • Create and join as many chats as you want using any modern web-browser
  • Send files of any type
  • Previews for images (.png, .jpeg, .gif)
  • Automatic detection of urls in messages
  • Automatic OpenGraph url previews
  • Automatic detection of email addresses (the user who send the message has the option to send a notification to the mentioned email address)
  • Last-seen and typing indicators

Chat Users

Your chat users are stored in the web client. This means your user is tied to the browser you use to access Freech. Notice that a new user is created for every chat you join. Each user is associated with a unique token, that will only be shared on user creation. To login to a chat as a given user, the client needs this token.

NPM Dependencies

Notice that all NPM dependencies / node_modules are packaged as files with Freech. This is intended to ensure that a Freech installation will always work correctly regardless of changes or updates to dependencies.


To run the Freech server you need to install MongoDB and NodeJS. If your system is ready to go, place the complete Freech application in a folder, configure it and execute the server.js file. If you want you can run Freech using a tool like forever to ensure it will run continuously. You need to make sure that the user or process executing server.js has read and write access for the Freech folder.


Make sure that your Freech folder is structured like follows:

    (server.crt) this is needed to use ssl/https
    (server.key) this is needed to use ssl/https

Configure the MongoDB connection by editing the file /secret/db.json according to the template below. If you set up a local MongoDB using the default settings, the below config should work as is.

  "host": "localhost",
  "port": 27017,
  "options": [
    { "n": "ssl", "v": false },
    { "n": "connectTimeoutMS", "v": 5000 },
    { "n": "maxPoolSize", "v": 10 }
  "db": "freech"

Configure how Freech sends emails by editing /secret/mail.json according to the template below. Do not change the /chat?{id} or /unsubscribe.html?{address} parts of the urls unless you use a custom web client.

  "auth": {
    "name": "Freech",
    "address": "",
    "user": "",
    "password": "YourPasswordGoesHere",
    "host": "",
    "port": 465,
    "ssl": true
  "url": {
    "root": "",
    "chat": "{id}",
    "unsubscribe": "{address}"

Finally configure the Freech server by setting the desired values in /server.js. Here you can change the log level, where the log will be stored, what port the Freech web server should use and wether you want to use SSL. If you choose to use SSL, you can also configure a redirect that will redirect from http to https.

You can’t perform that action at this time.