Skip to content
  • There are no suggestions because the search field is empty.

Humly Control Panel Installation - Linux

Note: This step is only for on-prem installations of the Humly Control Panel. If you have a cloud account, please skip this step.

Humly Control Panel should be installed on Ubuntu Linux 20 LTS, Ubuntu 22 LTS , or Ubuntu 24 LTS versions.

Ubuntu 24 LTS is supported from Humly Control Panel Version 2.3 onwards.

You can find Humly Control Panel downloads here.

Linux On-Premise Installation Prerequisites

  • Ubuntu Linux 64 bit, 20 or 22 LTS. Ubuntu 24 LTS requires Humly 2.3 or later.
  • A static IP address (required for HRD devices to connect to the server).
  • The HCP server must be accessible through the firewall on HTTP and HTTPS ports. Default ports are TCP 3000 and TCP 3002.
  • A user account with sudo permission.
  • Accessible booking system (e.g., Exchange / Office 365) over HTTPS port TCP/443.
  • Access to NTP server over port UDP/123.
  • Internet access to download and install dependent packages via apt.

Installation Steps

This guide uses Ubuntu Server 22 LTS connected via SSH.

  1. It is highly recommended to update and upgrade the OS and install the basic build packages before starting the installation. Run the following commands: 
    sudo apt install -y build-essential
    sudo apt update
    sudo apt upgrade
  2. Download the latest Humly Control Panel version and copy the installation file to your server.
  3. Extract the installation file using the tar command: 
    tar -xzf installation_v*.tar.gz
  4. A directory matching the HCP version should now have been extracted. Verify this by running the ls command.
  5. Change to the newly extracted directory and run the installation script: 
    cd v1.* && sudo bash install.sh
  6. The installation script will automatically detect the necessary tools and prerequisites required to run Humly Control Panel. To continue, select Yes by typing 1 and pressing Enter.
    Installation script – select Yes to continue
  7. Create credentials for the MongoDB database. MongoDB stores meetings, users, and Humly Control Panel settings. Set a username (e.g. humly_user), then set and confirm a password (e.g. humly_pass), and set the database name (e.g. humly_db). Press Enter after each field.
    Create MongoDB credentials
  8. Specify the database server address. The default is to install the database locally on the same server, in which case the address should be localhost:27017.
  9. Type the HTTP application port (default 3000) and press Enter.
    Set HTTP port
  10. Set a memory limit for the HCP application. The recommended value is 4096 MB. The recommended amount may vary depending on the number of HRD devices connected to the server.
    Set memory limit
  11. The application should now have installed successfully and post-installation messages will appear.
    Post-installation success message
  12. You should now be able to access Humly Control Panel via a web browser on the configured HTTP application port (default 3000).
  13. You can remove the installation files as they are no longer needed: 
    cd .. && sudo rm -r installation_v*.tar.gz
  14. HCP is now ready for booking system configuration.
  15. Open your web browser and navigate to http://localhost:3000, or http://<server IP or FQDN>:3000 if connecting from another machine.
  16. Depending on your browser, you may see a certificate warning because the default certificate is self-signed. You can replace it with a public TLS certificate in a later step. For now, accept the certificate to proceed.
    Certificate warning – step 1 Certificate warning – step 2

Once done with your initial setup, move on to Step 3: Connect HCP to Booking System.

Troubleshooting

Use the sections below if you run into issues during or after the Linux installation.

apt update / apt upgrade fails or packages cannot be downloaded

Possible causes:

  • The server does not have internet access.
  • DNS resolution is not working on the server.
  • The apt package list is outdated or corrupted.

Steps to resolve:

  1. Verify internet connectivity by running: ping -c 4 google.com
  2. If DNS is failing, check /etc/resolv.conf and ensure a valid nameserver is configured.
  3. Try fixing the apt package list by running: 
    sudo apt --fix-broken install
    sudo apt clean
    sudo apt update
  4. Confirm that the server can reach the internet on port TCP/443, as some apt repositories require HTTPS.

tar extraction fails or the extracted directory is not found

Possible causes:

  • The downloaded installation file is corrupted or incomplete.
  • The file was downloaded with an incorrect name or to a different directory.

Steps to resolve:

  1. Verify the file exists and check its size: ls -lh installation_v*.tar.gz
    A very small file size may indicate an incomplete download.
  2. Re-download the installation file from the official download page and transfer it to the server again.
  3. Ensure you are in the correct directory when running the tar command: pwd

Installation script fails or exits with an error

Possible causes:

  • Missing build dependencies or prerequisites.
  • The script was not run with sudo.
  • Insufficient disk space.
  • MongoDB port 27017 is already in use.

Steps to resolve:

  1. Ensure that build-essential and all updates are installed before running the script (see Step 1 above).
  2. Always run the installation script with sudo: sudo bash install.sh
  3. Check available disk space: df -h. At least 40 GB of free space is required.
  4. Check if port 27017 is already in use: sudo ss -tlnp | grep 27017
    If another process is using it, stop that process before re-running the installer.
  5. Review the terminal output carefully for specific error messages and share these with Humly Support if needed.

Humly Control Panel is not accessible after installation

Possible causes:

  • The HCP service is not running.
  • A firewall is blocking ports TCP 3000 or TCP 3002.
  • The wrong IP address or hostname is being used.

Steps to resolve:

  1. Check if the HCP service is running: 
    sudo systemctl status humly-control-panel
    If it is not active, start it: 
    sudo systemctl start humly-control-panel
  2. Check if the port is listening: 
    sudo ss -tlnp | grep 3000
  3. Verify that the Ubuntu firewall (UFW) allows the required ports: 
    sudo ufw allow 3000/tcp
    sudo ufw allow 3002/tcp
    sudo ufw reload
  4. Try accessing the panel locally first: http://localhost:3000. If this works, the issue is likely a network firewall between the client and the server.
  5. Confirm you are using the correct static IP address or FQDN of the server.

MongoDB fails to start or credentials are rejected

Possible causes:

  • The MongoDB service failed to start after installation.
  • Incorrect credentials were set during installation.
  • Port 27017 is blocked or already in use.

Steps to resolve:

  1. Check the MongoDB service status: 
    sudo systemctl status mongod
    Start it if needed: 
    sudo systemctl start mongod
  2. Verify that port 27017 is not in use by another process: 
    sudo ss -tlnp | grep 27017
  3. If the wrong credentials were entered during installation, you will need to uninstall and reinstall HCP, setting the correct MongoDB credentials during the re-installation.
  4. Check MongoDB logs for detailed error information: 
    sudo journalctl -u mongod --no-pager | tail -50

Browser shows a certificate warning or "Your connection is not private"

Possible causes:

  • The default self-signed certificate is in use and has not yet been replaced with a trusted SSL/TLS certificate.

Steps to resolve:

  1. This is expected behaviour with a fresh installation. You can bypass the warning during initial setup by clicking Advanced > Proceed in your browser.
  2. To resolve the warning permanently, replace the self-signed certificate with a valid public TLS certificate. This can be done in the HCP settings after the initial setup wizard is complete.
  3. Contact your IT administrator or reseller for guidance on obtaining and installing a TLS certificate.

HCP service crashes or restarts repeatedly after installation

Possible causes:

  • The memory limit set during installation is too low for the number of connected devices.
  • The MongoDB service is not running, causing HCP to fail on startup.

Steps to resolve:

  1. Check HCP service logs for errors: 
    sudo journalctl -u humly-control-panel --no-pager | tail -100
  2. Ensure MongoDB is running before starting HCP (see MongoDB fails to start above).
  3. If the memory limit is causing issues, reconfigure it by re-running the installation script and entering a higher value (recommended: 4096 MB or more depending on device count).
  4. Verify that the server meets the minimum hardware requirements: 2 CPU cores, 4 GB RAM, 40 GB storage.

Still need help?

If none of the steps above resolve your issue, please create a support ticket and include the following information:

  • The Ubuntu version (run lsb_release -a)
  • The HCP installer version used
  • A description of where in the process the issue occurred
  • Any error messages from the terminal or installation output
  • Relevant log output from: 
    sudo journalctl -u humly-control-panel --no-pager | tail -100
    sudo journalctl -u mongod --no-pager | tail -50