Mesibo On-Premise - Installing & Running Mesibo on your own premise or private cloud

Estimated reading time: 26 minutes

Mesibo On-Premise solution allows you to run the entire Mesibo real-time platform in your own premise OR private cloud. All the messages and calls go through your own data center and stay in your own database. All you have to do is download Mesibo On-Premise and run it in your own data center. That’s it!

Why On-Premise

Although our cloud services let you start immediately, there are several reasons why you should consider On-Premise.

Privacy and Data Security

One of the key reasons is to have ultimate control over your data. More than ever before, it has become imperative to protect and be more sensitive towards your user data - be it personal data, financial data, medical records, and also other reasons like GDPR, HIPPA, unauthorized harvesting of your data, companies selling, misusing your data for advertisement, to name a few. Cambridge Analytica Scandal is an example that your data is most safe when it’s within your control.

Mesibo On-premise offering puts you complete control of your data since everything runs on your own servers or private clouds. All the messages and calls go through your own data center and stay in your own database. And hence mesibo or anyone else have absolutely no access to the data.

Extendibility and other Technical Advantages

On-Premise offers many features which are not possible with the cloud deployment. For example, loadable modules that let you load your own code and enable tighter integration with your backend. You can interface Mesibo On-premise solution with machine learning and AI tools like Tensorflow, Matlab, and much more. Refer tutorials for more details.


Pricing is the most salient part of our On-premise offering. It comes to you at no additional cost - you only pay for the number of active users per month! No monthly commitment, no bandwidth charges, no storage charges, or any other hidden charges. This makes On-premise even more economical and attractive than our Cloud offering.

If you do not wish to host Mesibo on your own server infrastructure, you have the option of using the Cloud offering by Mesibo. Also, even when running On-Premise, you can always use Mesibo cloud as a back-up, gives you best of the both worlds.


  • All Mesibo features, including Messaging, Voice, and Video calling, Chatbots running from your own premise
  • Complete control over your data. All the messages and calls route through and stay in your own infrastructure
  • Unlimited bandwidth and Messages
  • Unlimited storage and data retention
  • Private and public deployment
  • Auto fallback to Mesibo cloud as a back-up, if required
  • Push notifications
  • Loadable modules and scripting

All these at no additional cost


Before we dive into installing and running mesibo On-Premise Platform on your server, ensure that you are:

  • Familiar with mesibo API and already using mesibo on our cloud services. If not, please refer to getting started guide and tutorials to familiarize yourself before setting up mesibo On-Premise.

  • Familiar with setting up a Linux server and MySQL database. If not, refer to online tutorials for the Linux distribution of your choice.

  • Although not essential, basic knowledge of setting up Docker and using Docker containers would be helpful. You can refer to Docker documentation and various online tutorials on Docker.


Mesibo On-Premise Platform requires the following:

  • Linux 64-bit server (or an always-on instance) with at least 2GB free RAM. Mesibo supports all the major Linux distributions that supports docker. It is tested on the following distributions:

    • RedHat / CentOS
    • Ubuntu
    • Mint
    • Fedora
    • Debian
    • SLES
    • Oracles Linux 7.x
  • MySQL (or MariaDB) database 8.x and later. Ensure to disable MySQL strict mode. mesibo will create necessary tables in the database and hence you do not need to worry about the database schema.

  • RAM - Approx 1KB per user and 4KB per simulataneous connection.

  • CPU - mesibo is very lightweight and hence any reasonable modern-day CPU should be good enough. mesibo on-premise has been load tested for 1 million phantom users load on a normal dedicated server with intel i7 6700. Note that we do not recommend running it on VPS, unless you are deploying it for a fairly low number of users, say a few thousand. If you are deploying on cloud, your instances must be always on. You can perform your own load testing to find a suitable configuration.

Should I recompile my apps to work with Mesibo On-Premise?

Definitely not. If your apps are using latest Mesibo APIs, you only need to configure your On-Premise server in Mesibo Console and tell Mesibo to redirect all your users to your own server. All your users will immediately stop using Mesibo cloud servers and start using your own servers. Rest everything remains the same.

Mesibo cloud servers use the same software as On-Premise. So whether you use Mesibo Cloud Service or setup a dedicated server running Mesibo On-Premise, there is absolutely no change in the way you use Mesibo APIs or deploy your application. In fact, in case your data-center has issues, you can always have the option of falling back to Mesibo Cloud Services, with just the click of a button.

Setting up Mesibo-On Premise

Although Mesibo is a highly sophisticated piece of software, we have ensured that it is straightforward to set up. You only need to provide bare minimum information about where the On-Premise platform should save the data (your database), Mesibo will take care of the rest.

To setup Mesibo On-Premise, follow the steps below:

Step 1 - Install Docker

Mesibo On-Premise server is distributed as a docker image so that you can easily install it on most Linux distributions. All you need is to install Docker to run it. If you have already installed and running Docker on your server, you can skip to Step 2.

You can install Docker by running the command below:

$ sudo curl -sSL | sh

Once Docker is installed, you need to start the Docker daemon. Most Linux distributions use systemctl to start services. If you do not have systemctl, use the service command.

  • systemctl:

    $ sudo systemctl start docker
  • service:

    $ sudo service docker start

Once the installation is over, you can verify it by running

$ sudo docker run hello-world

It should show something like:

Hello from Docker!
This message shows that your installation appears to be working correctly.

Step 2 - Download Mesibo On-Premise Platform

Download Mesibo On-Premise docker image by running the following command

$ sudo docker pull mesibo/mesibo

This will download and install Mesibo On-Premise platform on your server. However, before we launch it, we need to configure mesibo in the Mesibo console.

Step 3 - Configure Mesibo On-Premise

As mentioned earlier, Mesibo made On-Premise configuration straightforward. You don’t need to wrestle with complicated configuration files. Instead, the complete On-Premise configuration is done through Mesibo Console. All you need to do is to pass your app token to Mesibo On-Premise server, and it will automatically fetch and configure the entire server for you.

Login to Mesibo console, and select the application you want to configure on your On-Premise host. Make a note of the app token. You need to use this app token later to run Mesibo On-Premise Server.

App token Mesibo Console

Now, Go to App Settings → On-Premise Hosting in Mesibo Console. Here you will find two sections: Enable On-Premise and On-Premise Configuration. Enter all the required configuration for your On-Premise setup in the configuration section.

Warning: DO NOT turn ON the Enable On-Premise switch before configuring and running Mesibo On-Premise.

Console Screenshot

Following are the configuration entities:

  • Database Information - You will need a database for Mesibo, and a user who has all privileges for accessing and modifying it. Mesibo requires this information (database host, name, username and password) to access the database.

Config Complete

There are two more configuration checkboxes which you can enable if required:

  • Privately Hosted - In this mode, mesibo console will not check for the correctness of hostname, or any network connectivity. Select this if you are running Mesibo On-Premise in your private network/intranet setup.

  • Auto Fallback - Enable this if you want to fallback to cloud when your data-center is having an issue. Note that, some of the offline messages will not be delivered in fallback mode since Mesibo cloud has no access to your database.

Step 4 - Configuring TLS Certificate

Mesibo uses the latest Transport Layer Security (TLS) which is the successor to SSL. To enable TLS, you need to configure a valid TLS certificate with your Mesibo On-Premise installation.

Although Mesibo can automatically generate a self-signed certificate for you, it is recommended that you configure a valid CA-signed certificate. This is especially required for JavaScript code since all the major web browsers will throw a warning when using a self-signed certificate.

You can use any existing certificate which you are using with your web server, OR purchase it from any provider of your choice, OR use Letsencrypt which is a free service (recommended) to get a secure certificate.

mesibo loads TLS/SSL certificates from /certs folder inside the docker container. To configure your certificate, you need to map a folder on your host containing your certificate files to /certs folder using -v option as shown in the next step. You need to ensure that the folder contains all your certificate file - certificate (cert.pem), private key (privkey.pem), and CA chain (chain.pem) files. For example,

$ ls /etc/letsencrypt/archive/
README  cert.pem  chain.pem  fullchain.pem  privkey.pem

Note that using a wild card certificate is not recommended.

Step 5 - Run Mesibo

We are now all set to run Mesibo. You will notice that the Running Status field in console showing “Not Running”.

You can now run Mesibo using following command (recommended):

$ sudo docker run -v /etc/letsencrypt/archive/ --net=host \
		-d mesibo/mesibo <APP_TOKEN>

You need to specify the APP_TOKEN which you noted in Step-3 above. For example,

App token Mesibo Console

For example,

$ sudo docker run -v /certs:/etc/letsencrypt/archive/ --net=host \
		-d mesibo/mesibo iqmr059ms2yopxhc2sayx05ba2l5cralockbicqjsvv1nsqxs0x1yclfv0qvyg1q 

On sucessfull launch of Mesibo, the output log should look like below:

E3108-082633-480 (1): Mesibo Build: Aug 29 2020 15:39:08
E3108-082633-506 (1): PID: 1
E3108-082633-775 (1): Local IP Address:
E3108-082634-580 (10): *** onp_message: On-Premise not enabled - login to Mesibo console to enable it
E3108-082634-639 (10): Generating TLS certificate for
I3108-082635-167: Starting mesibo

You can view logs using

$ sudo docker logs <CONTAINER_ID>

You can find the CONTAINER_ID using docker ps command as shown below:

$ sudo docker ps
CONTAINER ID        IMAGE                 COMMAND                  CREATED             STATUS              PORTS               NAMES
7508d3d78992        mesibo/mesibo  "/mesibo/bin/mesibo …"   8 seconds ago       Up 7 seconds                            blissful_ramanujan

If your logs contain any errors indicating failure to start Mesibo, refer to the troubleshooting section.

Now, check Running status of your server from the ‘Mesibo console → App Settings → On-Premise Hosting. If successful, the Running Status field will contain your hostname instead of Not running`.

Enable On-Premise screenshot

If your On-Premise server is setup properly continue with the next step, else refer to the troubleshooting section.

Step 5 - Enable On-Premise

Now, it’s time to enable On-Premise from the console. Once you enable On-Premise from the console, all your users will be notified to use your On-Premise server instead of Mesibo cloud.

Enable On-Premise screenshot

Turn on the On-Premise switch and your app users will start connecting to your On-Premise server immediately and you will start observing logs like following:

: login successful: root (uid xxxx) aid: (xxxx) 

Congratulations! You are now UP with Mesibo running on your own premise.

Firewall Settings

Mesibo listens on TCP ports 513, 5222, 5223, 5228, 4443, 5443 and 8443. Ensure that these ports are open on your Linux host so that your users can connect to your On-Premise server. Mesibo on-premise also requires an outgoing connection to for authenticating and billing. Ensure that your firewall does not block it.

Depending on your Linux distribution, there are different ways to configure firewall, for example, to open port `5222’, you’d issue the following command depending on your system:

  • If your system has firewall-cmd (Red Hat Enterprise Linux, CentOS, Fedora, and variants)

    $ sudo firewall-cmd --add-port 5222/tcp
  • If your system has iptables (Red Hat Enterprise Linux, CentOS, Fedora, and variants)

    $ sudo iptables -A INPUT -p tcp --dport 5222 -j ACCEPT
  • If your system has ufw (Ubuntu, Debian, and variants)

    $ sudo ufw allow 5222/tcp
  • If you are running mesibo on-premise on public cloud like AWS or Google, go to respective services configuration tools to open there ports.

Chatbot and Scripting

Mesibo on-premise comes with a powerful chatbot & scripting engine that allows you to run custom Javascript to process each message your users are sending and receiving. You can create a JavaScript script that can carry out your own decision logic to process each message to create interesting chatbots and apps. Refer to Chatbot and Scripting Documentation to learn more.

If you are using Chatbot and Scripting with your on-premise deployment, you need to pass an additional command-line argument to specify the directory where on-premise can store javascript files.

-v <some folder>:/mesibo

Local Configuration

If you prefer not to share your database credentials on the mesibo console and instead like to configure it locally, you can create a configuration file /etc/mesibo/mesibo.conf and configure it as follows:

database {

	host=<db host>
	name=<db name>
	user=<db username>
	pass=<db password>

mesibo on-premise assumes that your database is listening on port 3306. If your database is listening on other port, you may specify it using a port parameter.

You may also specify other parameters. Note that configuration file has priority over command line parameters.

server {

	token=<app token>
	hostname=<host name>
	validate=<validate hostname>

ssl {
	path=<certificates path>

You still need to configure dummy database credentials in the console. Anything you configure in /etc/mesibo/mesibo.conf overrides the console configuration.

You will also need to pass an additional parameter -v /etc/mesibo:/etc/mesibo to docker so that mesibo can access the configuration file.

Updating Mesibo On-Premise Server

Always ensure that you have the latest version of Mesibo Docker Image running. To update your mesibo on-premise image, run:

$ sudo docker pull mesibo/mesibo

Stopping On-Premise

To stop on-premise, get the CONTAINER_ID of the Mesibo docker container by using

$ sudo docker ps

Now, stop this container using CONTAINER_ID

$ sudo docker stop <CONTAINER_ID>

Command line arguments

mesibo takes a few command line arguments which you need to specify before the token.

  • --hostname= or -h , this is ignored if certficate has the host name
  • --private or -p if mesibo is deployed on a private network. No hostname or IP validation will be performed

Deploying with a Cloud Service Provider

All major cloud service providers support running docker containers. Hence you can easily run mesibo. However, you may need to configure the following:

  • If you are running a VM instance having the only private address, pass -p parameter before the token

  • You must open all the required ports in the firewall settings in your providers control panel

To create an on-demand instance of Mesibo in the cloud, refer to respective documentation on running Docker containers :

Migrating from mesibo cloud to on-Premise

Since mesibo will NOT have any access to your on-premise setup or database, there are two important aspects that you need to handle yourselves when migrating from Cloud to On-Premise.

Group Management

If your apps are using real-time group APIs, group management is taken care by mesibo on-premise. You can skip this section in that case.

However, if you are using group management APIs using backend APIs, you need to provision group configuration. Mesibo will create two tables groupstable and members in the database. You need to populate groups and groups member yourself. This is because of the fact that mesibo backend APIs have no access to your database.

For example, you can add a group to the database as following:

mysql> insert into groupstable set aid='Your APP ID', name='Your Group Name', expiry='2021-01-01 00:00:00';

You can then add groups members using gid in group table and uid from the users table.

It is highly recommended that your app uses real-time group management APIs instead of backend based group management APIs.

Sending messages from the backend to users

On-premise takes care of messages and calls between all your users and groups without any changes from your side. However, if you were using mesibo REST API to send messages from your backend to your users in your mesibo cloud deployment, the same setup will not work in on-premise since the mesibo REST API does not have access to your on-premise instance and the database. Hence, you need to populate the database yourself as described below.

When you install on-premise, a table ‘apimessages’ will be created in your database. To send a message from the backend, you need to populate apimessages table yourself.

Following are columns of apimessages table:

aid - Your app id (numerical, check console for your APP ID)
uid - destination UID
src - source UID
gid - group id, zero otherwise
expiry - expiry in seconds
ts - unix_timestamp() - current or the future value to schedule
message - message

Since you will be adding entries manually, your on-premise server will not know about the new message. So either you can wait for it to check regularly or send a trigger to on-premise so that it instantly knows there is a message and send it immediately. You can send trigger by sending any message to UDP port 18111

Below is sample PHP code for sending trigger or you can use similar from your language of choice

$socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
$rv = socket_sendto($socket, "mesibo", 6, "<on-premise docker ip adress>", 18111);

Dynamically Loadable Modules and Scripting

Mesibo On-Premise is designed by developers for developers. Its dynamically loadable module architecture lets you load your own code for deeper integration with your infrastructure, enabling you for unlimited creative possibilities. This makes Mesibo, the most compelling real-time communication platform existing today.

We will soon publish a new tutorial on this topic.

Troubleshooting & FAQ

Although mesibo on-premise is simple to set up and run, below is a possible list of set up issues and commonly asked questions. Some of the issues (for example, MySQL, networking, etc. ) may require you to launch a shell inside the docker container bypassing the mesibo so that you set up independently without launching or involving mesibo.

You can enter the docker shell (bypassing mesibo) by running the following command, the mesibo will not be launched in this case.

$ sudo docker run -it --entrypoint /bin/bash -v /etc/letsencrypt/archive/ --net=host -v /etc/mesibo:/etc/mesibo mesibo/mesibo

You will be presented with a bash shell where you can enter regular Linux commands to troubleshoot various issues.

MySQL Issues

If you have trouble connecting to your MySQL server, you can directly use the mysql command from the docker shell to troubleshoot.

# mysql -h <dbhost> -D <dbname> -u <dbusername> -p

One common mistake is to specify localhost or for the database host which generally does not work for the docker environment. You should specify the actual host or the IP address and your database should grant access to the user from the docker host or the IP address (and not the localhost). You can find a docker IP address using the ifconfig command.

Note that if mysql command can not access your database, then even mesibo can’t since mesibo uses MySQL. You will find plenty of tutorials online (and also on stackoverflow) to debug your MySQL connection issues.

Certificate Issues

If you are having a certificate related issue, ensure that you have correctly followed all the instructions in Step 4 - Configuring TLS Certificate above.

If you are still having issues, enter the docker shell as explained above and try the following command.

# ls /certs
README  cert.pem  chain.pem  fullchain.pem  privkey.pem

You should see all your certificate files in the /certs folder. If not,

  1. Check folder for permissions issues, and the folder name passed using -v option.
  2. Ensure that folder you have passed is the real folder and not the link (symlink or hard link). This is especially true for Letsencrypt live folder which is a link, try using archive folder instead (for example, /etc/letsencrypt/archive/
  3. Alternatively, try moving your files to a new folder with friendly permissions like 0755 and try using the new folder.

Note that If docker container can’t access your files, then even mesibo can’t since mesibo runs inside the docker container. We can not help you here. You will find plenty of tutorials online (and also on stackoverflow) that shows how to mount your folder on a docker container.

If you can see all your certificates, you can check the certificate validity by running the following commands

# cd /certs
# openssl x509 -in cert.pem -text -noout
This should print certificate info. Check CN and validity fields.

# openssl rsa -in privkey.pem -check
This should print valid key information

IP Address Mismatch

Ensure that you are running mesibo on-premise on a valid host. For example, if your domain name is ‘’ and the IP address configured for your domain name in your DNS is ‘’, you need to ensure that the same IP address is configured on the host machine where you are running mesibo. mesibo on-premise checks for a valid IP address to ensure that the IP address matches the hostname (or the certificate host). mesibo on-premise will print an error and exit if the matching IP address is not found on your machine.

However, there are instances when you need to override it, say, in a VM setup (say, Google Cloud or Amazon EC2) where VM is running on a private IP, not matching with the actual host address. In such cases, you can disable the check using the -p option before the app token, as shown below. Note that your users will not be able to connect if you run mesibo on an arbit machine.

$ sudo docker run -v /etc/letsencrypt/archive/ --net=host \
		-d mesibo/mesibo -p <APP_TOKEN>

Connection Issues

Ensure that your have configured the firewall as described in the Firewall settings above.


On-premise server prints error(s) to show you the correct status even if it is “ready to connect”. Try to connect a client if it is ready. If the client does not connect, check the incoming firewall (invariably an issue when running it on cloud providers like AWS, Azure, etc). You can also use netcat to check the connectivity.

$ netcat <IP> 5222

Contact Us

You can contact us with the result of all the above information if you still need help. Ensure to send the complete logs and describe what all have you tried. Note that, when you are running on-premise, we have absolutely no information about your setup. Hence, send us even trivial details like IP addresses (use ifconfig or ip addr), certificate details, commands you have tried, etc.


For a more detailed FAQ section on On-Premise refer

I am currently using Mesibo Cloud services. If I enable On-Premise, how long will it take to switch connection to my server?

As soon as you enable On-Premise in the console, your users will start getting connected to your On-Premise server. Please ensure that you have made the necessary configuration in the console and the Running Status in console displays your hostname before you enable On-Premise.

Can I switch from Mesibo On-Premise back to Mesibo Cloud Service ?

Yes, if you would like your users to switch from On-Premise server to Mesibo cloud server, first disable On-Premise in the console and then stop your docker container which is running mesibo. Your users will now get connected to Mesibo Cloud.

I have enabled On-Premise and my server is running, how do I know if my app is connected to my server?

You can check the logs for your server using

$ sudo docker logs CONTAINER ID 

When a user on your app logs-in, you’ll get a login entry for that user.

What happens if I have enabled On-Premise and my server is not running?

There are two possibilities:

  • If Auto Fallback is not enabled and your server is not running and you have enabled On-Premise, your users will not be able to connect and hence will fail to get your service.

  • If Auto Fallback is enabled and your server is not running and you have enabled On-Premise, your users will switch to Mesibo cloud after a few retries.

What happens if a user is connected to my server and I disable On-Premise from the console?

If your server is running, your users will continue to connect to your On-Premise server since they do not know about you disabling On-Premise server.

However, if you also stop your docker container running Mesibo, your users will be redirected to Mesibo cloud after a few retries and will connect there since you have disabled On-Premise.

Can I run Mesibo on a Cloud Service Provider?

All major cloud service providers support running docker containers. Please refer to respective documentation for different providers such as AWS, Azure, Google Cloud, etc.

I am confused between On-Premise Vs. Cloud offering, which one is better?

You can’t go wrong with either model. While our Cloud service let you start immediately without installing anything, the On-Premise model offers ultimate flexibility, control of your data, loadable modules, interface with machine learning and AI tools and much more. The pricing is same, however, On-Premise model can work out more cost-effective as there are no charges other than per active user charges. On another hand, you pay for bandwidth and storage charges in our cloud offering.

Will the backend API URL change when I use on-premise?

No, the backend API URL will remain the same - you will use the even when using on-premise. When running on-premise, you only need to use backend APIs for creating users. For everything else, you can use real-time APIs.

Getting Error: MySQL Connection Failed - Can’t connect to MySQL server in server logs

  1. Ensure that database host, name and credentials are correctly configured in On-Premise configuration.
  2. Ensure that you have granted the necessary permissions to access your database from the docker container.
  3. Check your database host firewall configuration and ensure that, it is configured properly for allowing connections from docker container.

Getting Error: Unable to verify app token - network error in server logs

Check your firewall configuration and verify that it is configured to allow connections from your docker container. Then, restart your docker container.

chat system on-premise, messaging platform, chat api platform, voice, video calling on-premise, installing chat platform on private cloud, mesibo communication platform