How to Install OrangeHRM

Prepare the Server

Start with a fresh Ubuntu Server 22.04 LTS installation. This can be a cloud VPS from any provider (DigitalOcean, Hetzner, Linode, AWS Lightsail) or a physical server. A VPS with 2 CPU cores, 2 GB RAM and 20 GB SSD storage is sufficient for organizations up to 200 employees.

Connect to the server via SSH and update all packages:

sudo apt update && sudo apt upgrade -y

Set the correct timezone for your organization, which affects timestamps throughout the HR system:

sudo timedatectl set-timezone America/New_York

Replace America/New_York with your timezone. Use timedatectl list-timezones to see all available options.

Install Nginx

Nginx serves as the web server and reverse proxy for OrangeHRM. Install it from the default Ubuntu repository:

sudo apt install nginx -y
sudo systemctl enable nginx
sudo systemctl start nginx

Verify Nginx is running by opening your server's IP address in a browser. You should see the default Nginx welcome page. If you have a firewall enabled, allow HTTP and HTTPS traffic:

sudo ufw allow 'Nginx Full'

Install PHP and Extensions

OrangeHRM requires PHP 8.1 or newer. Ubuntu 22.04 includes PHP 8.1 in its default repositories. Install PHP-FPM (FastCGI Process Manager) along with the extensions OrangeHRM needs:

sudo apt install php8.1-fpm php8.1-mysql php8.1-mbstring \
  php8.1-xml php8.1-curl php8.1-gd php8.1-zip \
  php8.1-intl php8.1-opcache php8.1-ldap -y

Adjust PHP settings for HR use. Edit the PHP-FPM configuration file at /etc/php/8.1/fpm/php.ini and update these values:

upload_max_filesize = 20M
post_max_size = 25M
memory_limit = 256M
max_execution_time = 120

These settings allow employees to upload documents up to 20 MB (contracts, ID scans, certificates) and give the system enough memory and execution time for report generation and data imports. Restart PHP-FPM after making changes:

sudo systemctl restart php8.1-fpm

Install and Configure MySQL

Install MySQL 8.0 and run the security hardening script:

sudo apt install mysql-server -y
sudo mysql_secure_installation

The security script prompts you to set a root password, remove anonymous users, disable remote root login and remove the test database. Answer yes to all prompts.

Create a dedicated database and user for OrangeHRM. Log into MySQL and run:

sudo mysql -u root -p

CREATE DATABASE orangehrm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'orangehrm'@'localhost' IDENTIFIED BY 'your_strong_password_here';
GRANT ALL PRIVILEGES ON orangehrm.* TO 'orangehrm'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Use a strong, unique password for the database user. This password will be entered during the OrangeHRM installation wizard. The utf8mb4 character set ensures proper handling of international characters in employee names and addresses.

Download OrangeHRM

Download the latest OrangeHRM Starter release. Check the official OrangeHRM GitHub repository for the current version number and download the release archive:

cd /var/www
sudo wget https://github.com/orangehrm/orangehrm/releases/download/v5.x/orangehrm-5.x.zip
sudo apt install unzip -y
sudo unzip orangehrm-5.x.zip
sudo mv orangehrm-5.x orangehrm

Replace 5.x with the actual latest version number from the releases page. Set the correct ownership so Nginx can serve the files and PHP can write to necessary directories:

sudo chown -R www-data:www-data /var/www/orangehrm
sudo chmod -R 755 /var/www/orangehrm

Configure Nginx for OrangeHRM

Create an Nginx server block configuration for OrangeHRM. Create a new configuration file:

sudo nano /etc/nginx/sites-available/orangehrm

Add the following configuration, replacing hr.yourcompany.com with your actual domain:

server {
    listen 80;
    server_name hr.yourcompany.com;
    root /var/www/orangehrm/web;
    index index.php;

    client_max_body_size 25M;

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

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

    location ~ /\.ht {
        deny all;
    }
}

Enable the site and test the configuration:

sudo ln -s /etc/nginx/sites-available/orangehrm /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Note that the document root points to the web subdirectory inside the OrangeHRM installation, not the installation root. This is important for security, as it prevents direct access to configuration files and the source directory.

Run the Web Installer

Open your domain in a browser (http://hr.yourcompany.com). The OrangeHRM installation wizard launches automatically and walks through several screens:

System check: the installer verifies that all PHP extensions are installed, file permissions are correct and the server meets minimum requirements. If any check fails, install the missing extension or fix permissions before proceeding.

Database configuration: enter the database host (localhost), database name (orangehrm), database user (orangehrm) and the password you created earlier. The installer tests the connection and creates all necessary tables.

Admin account: create the initial administrator account with a username, password and email address. This account has full access to all OrangeHRM features. Use a strong password and store it securely.

Confirmation: the installer runs database migrations, populates reference data (countries, currencies, leave types) and creates the initial configuration. When complete, it redirects you to the login page.

Log in with the admin credentials you just created. You should see the OrangeHRM dashboard with quick access to employee management, leave, time and recruitment modules.

Secure and Finalize

With OrangeHRM running, complete these security and configuration tasks before adding employee data.

Install SSL: encrypt all traffic with a free certificate from Let's Encrypt using Certbot:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d hr.yourcompany.com

Certbot automatically modifies the Nginx configuration to serve HTTPS and sets up automatic certificate renewal. Verify renewal works with sudo certbot renew --dry-run.

Remove installer files: after confirming the installation works, remove or restrict access to the installer directory to prevent anyone from re-running installation:

sudo rm -rf /var/www/orangehrm/installer

Set up backups: create a daily cron job that dumps the MySQL database and copies the upload directory to a backup location. At minimum, back up the database daily and transfer copies offsite weekly:

mysqldump -u orangehrm -p orangehrm | gzip > /backup/orangehrm-$(date +%Y%m%d).sql.gz

Configure email: in OrangeHRM, navigate to Admin, then Configuration, then Email Configuration. Set up SMTP settings so the system can send leave approval notifications, password reset emails and recruitment correspondence. You can use your organization's mail server, Gmail SMTP or a transactional email service like Amazon SES.

Initial data setup: before inviting employees to the system, configure the organization structure (Admin, then Organization, then General Information), department list, job titles, pay grades, work shifts, leave types and leave entitlement rules. Import employee data using the CSV import feature under PIM, then assign user accounts so employees can access self-service features.