How to Setup ICE HRM on Ubuntu 24.04 with Nginx

Install Nginx HTTP server on Ubuntu

Nginx is the web server that receives incoming requests and passes them to your ICE HRM application on Ubuntu 24.04. It is available in the default Ubuntu repositories, so you can install it 💿 from the terminal with the standard package manager commands. It is best to install it first, because the other components are tested through it.

Open the Ubuntu terminal and run the commands in the block below to install the 💿 Nginx web server. The first command refreshes the package list and the second installs Nginx. If you are asked to confirm, type Y and press Enter.

sudo apt update
sudo apt install nginx

Once Nginx is installed, you can use the commands below to start it, stop it, and enable it so it starts automatically every time the server boots. Ubuntu usually starts Nginx right after installation, but enabling it explicitly makes sure it survives a reboot.

sudo systemctl stop nginx
sudo systemctl start nginx
sudo systemctl enable nginx

To test that Nginx is running, open your web browser and browse to the server’s localhost or IP address. If you are working on the server itself, use localhost. From another computer, use the server’s IP address.

http://localhost

When you see Welcome to nginx!, the Nginx HTTP server is installed and working. If the page does not load from another computer, check that the service is running and that no firewall on the server is blocking port 80.

For more help with installing Nginx on Ubuntu, see the link below.

How to install Nginx on Ubuntu

Install the MariaDB database server on Ubuntu

MariaDB stores all the employee records and settings for your HR system. It is in the default Ubuntu repositories, so a single package installation sets up the database engine. The next few steps install it, confirm it is running, and check that you can log in.

To install and use the MariaDB database server, follow the instructions below.

Open the Ubuntu terminal and run the commands in the block below to install the MariaDB database server.

sudo apt update
sudo apt install mariadb-server

Once MariaDB is installed, use the commands below to stop it, start it, and enable it so it starts automatically when the server boots. You only need the stop and start commands when you want to restart the database by hand. The enable command is the one that matters for a normal setup.

sudo systemctl stop mariadb
sudo systemctl start mariadb
sudo systemctl enable mariadb

Run the commands below to check that the MariaDB database server is installed and working.

sudo mariadb

After you run these commands, you are logged in to the MariaDB console and see a message similar to the one below.

Welcome to the MariaDB monitor.  Commands end with ; or g.
Your MariaDB connection id is 32
Server version: 10.11.2-MariaDB-1 Ubuntu 23.04

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or 'h' for help. Type 'c' to clear the current input statement.

MariaDB [(none)]> 

This message tells you the server is installed and running. You can leave the console for now. The next section logs in again to create the ICE HRM database.

For more help with installing MariaDB, see the links below.

• How to install MariaDB on Ubuntu Linux
• MariaDB without password prompt

Create an ICE HRM database

ICE HRM needs its own database to store user data and system settings. Create a database and a dedicated database user from the MariaDB command line. A dedicated user is safer than letting the application connect as the MariaDB root account. If the application is ever compromised, the damage stays limited to this one database.

In this setup, we will create a database called icehrmdb and a user account called icehrmdbuser.

The user icehrmdbuser is given full access to the icehrmdb database, so ICE HRM can read and write all the data it needs.

You can do all of this with the commands below.

First, log in to the MariaDB database server:

sudo mariadb

Then run the commands below to create the database, create the user and grant access:

CREATE DATABASE icehrmdb CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER icehrmdbuser@localhost IDENTIFIED BY 'type_your_password_here';
GRANT ALL ON icehrmdb.* TO icehrmdbuser@localhost WITH GRANT OPTION;
FLUSH PRIVILEGES;
exit

Write the password down, because you need it again in the installation wizard. Each SQL command should answer with a short "Query OK" message. If you see an error instead, check for a missing semicolon or a mistyped quote.

Install PHP on Ubuntu Linux

PHP runs the backend code that makes ICE HRM work. Nginx cannot run PHP by itself. It hands PHP requests to PHP-FPM, so you install PHP together with php-fpm and the extensions the application needs. Ubuntu 24.04 ships PHP 8.3 in its default repositories, so that is the version you get unless you add another source.

Run the commands in the block below to install the latest PHP version from the Ubuntu repositories along with the required modules.

sudo apt install php-fpm php-intl php-mysql php-curl php-cli php-zip php-xml php-gd php-common php-mbstring php-xmlrpc php-bcmath php-sqlite3 php-soap php-ldap php-imap

Remember the PHP version you end up with. The PHP-FPM socket path in the Nginx server block later on must match that version.

How to install PHP on Ubuntu Linux

Download ICE HRM files

Next, put the ICE HRM application files on your server. You download the latest package from the official source into a temporary directory, extract it, and then move it into the Nginx root folder.

To make sure you always install the latest version, check the download page for ICE HRM. Copy the download link for the archive and use it in the commands below. If you downloaded the archive to your own computer instead, upload it to the server before you extract it.

First, move to the /tmp/ directory and download the ICE HRM files. Next, extract the contents into the ICE HRM folder in the Nginx root directory. In this guide that folder is /var/www/html/icehrm.

The final step is to change the ownership and permissions. This lets the Nginx web server read and write the files safely, which ICE HRM needs for uploads and its own settings. Skipping this step is a common reason for blank pages or permission errors in the installation wizard.

Nginx runs as the www-data user on Ubuntu, so that user must own the application files. Run the following commands: `sudo chown -R www-data:www-data /var/www/html/icehrm` and `sudo chmod -R 755 /var/www/html/icehrm`. The first command gives ownership to the web server user. The second lets everyone read and run the files, but only the owner write to them. This ensures the web server can access and write to the ICE HRM files.

cd /tmp
wget https://phoenixnap.dl.sourceforge.net/project/icehrm/icehrm_v33.5.0.OS.zip
unzip icehrm_*.zip
sudo cp -rf icehrm_v33.5.0.OS /var/www/icehrm
sudo chown -R www-data:www-data /var/www/icehrm/

With the steps above finished, configure the Nginx web server so it serves the ICE HRM content. Nginx does this through a virtual host, also called a server block.

Run the commands below to create an Nginx virtual host file for ICE HRM. The command opens a new, empty file in a text editor.

sudo nano /etc/nginx/sites-available/icehrm.conf

Then copy and paste the content block below into the file. Change the server name in the block to your own domain name or server IP address. Also check that the PHP-FPM socket path in the block matches the PHP version you installed. On Ubuntu 24.04 that is normally PHP 8.3.

server {
    listen 80;
    listen [::]:80;
    root /var/www/icehrm;
    index  index.php;
    server_name  icehrm.example.com;

    access_log /var/log/nginx/example.com.access.log;
    error_log /var/log/nginx/example.com.error.log;   

  # For Rest API
    location /app/api/ {
        try_files $uri /app/api/index.php?/$uri&$args;
    }

    # Prevent access to data directory
    location /app/data/ {
        deny all;
        return 404;
    }
    
    # prevent access to the core directory
    location /core/ {
        deny all;
        return 404;
    }

    location ~ .php$ {
         include snippets/fastcgi-php.conf;
         fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
         fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
         include fastcgi_params;
    }


}

Save the file and close the editor.

Now enable the virtual host for ICE HRM and restart Nginx so the site becomes available. Nginx does not use the Apache a2ensite tool. Instead, you link the configuration file from the sites-available folder into the sites-enabled folder, then restart the service. Run the commands in the block below to do both. If the restart fails, the most likely cause is a typo in the server block, so reopen the file and check it.

sudo ln -s /etc/nginx/sites-available/icehrm.conf /etc/nginx/sites-enabled/
sudo systemctl restart nginx.service

Setup Let’s Encrypt SSL/TLS for ICE HRM

Let's Encrypt gives you a free SSL/TLS certificate, which turns on HTTPS for ICE HRM. This matters here because the login page and employee data should not travel over plain HTTP. You request the certificate and configure Nginx to use it. This needs a real domain name that points to your server, and ports 80 and 443 must be open.

Please read the post below for more help with installing and creating Let’s Encrypt SSL certificates for Nginx.

How to set up Let’s Encrypt SSL certificate for Nginx on Ubuntu Linux

Once Nginx has restarted, open your browser and go to the server hostname or IP address you set in the Nginx server block. If you set up HTTPS, use the https address.

http://icehrm.example.com

The ICE HRM installation wizard should appear. If you see the default Nginx page instead, the new server block is not being used. Check that the site is linked and that the server name matches the address you typed. If you see a download prompt or raw PHP code, PHP-FPM is not connected to Nginx correctly.

Type in the database name, user name and password you created earlier. Then click the Test Database Connectivity button. If the test fails, recheck the database name, user name and password. Also confirm that the user was granted access to the database.

If the test succeeds, click the Install Application button to begin the installation. It takes a short time while ICE HRM creates its tables in the database.

Log in with the default user name and password:

• admin
• admin

ICE HRM should now be ready to use. Change the default admin password straight away, since anyone who knows the default can sign in to your HR data.

That should do it!

Conclusion:

In summary, installing ICE HRM on Ubuntu using Nginx involves several key steps:

• Install Nginx: Set up the Nginx web server to handle web traffic efficiently.
• Install MariaDB: Implement the MariaDB database server to manage your application’s data.
• Create ICE HRM Database: Establish a dedicated database for ICE HRM and configure user access.
• Install PHP: Ensure that the necessary PHP components are available for the application to function.
• Download ICE HRM: Obtain the ICE HRM application files and place them in the designated web directory.
• Configure Nginx: Set up a virtual ICE HRM host to properly manage site requests.
• Secure with SSL: Implement Let’s Encrypt to provide a secure HTTPS connection.
• Run the Installation Wizard: Complete the setup by entering your database credentials and finalizing the installation.

These steps give you a working ICE HRM deployment for managing HR tasks. After the first login, change the default admin password and set up HTTPS if you have not already. Then add your company details and employees.