A Complete Beginner's Guide on how to Self-Host OrangeHRM Using Docker

Why should we Self-Host OrangeHRM? 

Human Resource Management Systems (HRMS) have become an essential part of modern organizations, helping businesses manage employee information, recruitment, leave, performance, attendance, and other HR processes more efficiently. As organizations continue to embrace digital transformation, many are looking for solutions that provide greater control over their data while reducing the cost of cloud-based subscriptions.
One of the most popular open-source Human Resource Information Systems (HRIS) is OrangeHRM. It offers a comprehensive suite of HR management features that enable organizations to streamline daily HR operations while maintaining full ownership of their data through self-hosting. Some of its key modules include:

• Employee Information Management (PIM)

• Leave Management

• Recruitment

• Performance Management

• Time and Attendance

• Reports and Analytics

• User and Role Management

Traditionally, deploying a web application such as OrangeHRM required manually installing and configuring a web server, PHP, a database server, and their supporting dependencies. This process could be time-consuming, prone to configuration errors, and difficult to maintain.

Docker simplifies this process by packaging OrangeHRM and its required services into isolated containers. This approach provides a consistent deployment environment, simplifies upgrades, improves portability, and makes it much easier to manage the application across different operating systems.

In this guide, you will learn how to self-host OrangeHRM using Docker Compose on Windows. The same approach can also be applied to Linux and macOS with only minor adjustments. By the end of this tutorial, you will have a fully functional OrangeHRM instance running locally, providing a solid foundation for learning, testing, development, or future production deployments.

What You’ll Build 

By the end of this tutorial you’ll have:

Docker
│
├── OrangeHRM
│
├── MySQL
│
└── Persistent Database Volume

Accessible through: http://localhost:8080 (opens in a new tab)

Prerequisites

Before starting, ensure you have:
• Docker Desktop installed
• Docker Compose installed (included with Docker Desktop)
• Internet connection
• Minimum 4 GB RAM
• Windows 10/11, Linux, or macOS

Verify Docker installation:

docker — version

docker compose version

Expected output:

Docker version xx.xx.xx

Docker Compose version xx.xx.xx

Project Structure

Create a dedicated folder for OrangeHRM.

C:
│
└── docker
 │
 └── orangehrm
 │
 └── docker-compose.yml

Open PowerShell.

Navigate to the folder.

cd C:\docker\orangehrm

Create docker-compose.yml
Create a new file named
docker-compose.yml

Paste the following configuration:

services:
 db:
 image: mysql:8.0
 container_name: orangehrm-db
 restart: unless-stopped

 environment:
 MYSQL_ROOT_PASSWORD: rootpassword
 MYSQL_DATABASE: orangehrm
 MYSQL_USER: orangehrm
 MYSQL_PASSWORD: (YOUR PASSWORD)

 command: >
 — default-authentication-plugin=mysql_native_password

volumes:
 — mysql_data:/var/lib/mysql

 orangehrm:
 image: orangehrm/orangehrm:latest
 container_name: orangehrm
 restart: unless-stopped

 ports:
 — “8080:80”

 environment:
 ORANGEHRM_DATABASE_HOST: db
 ORANGEHRM_DATABASE_USER: orangehrm
 ORANGEHRM_DATABASE_PASSWORD: (YOUR PASSWORD)
 ORANGEHRM_DATABASE_NAME: orangehrm

 depends_on:
 — db

volumes:
 mysql_data:

Tip: If Docker displays a warning that the version attribute is obsolete, you can safely remove it. Modern versions of Docker Compose no longer require it.

Download the Images

Pull the required Docker images.

docker compose pull

Docker downloads:
• MySQL
• OrangeHRM

Start OrangeHRM

Launch the containers.

docker compose up -d

Expected output:

✔ Network created
✔ Volume created
✔ orangehrm-db Started
✔ orangehrm Started

Verify Everything Is Running

Run:

docker ps

Expected output:

CONTAINER ID IMAGE
orangehrm/orangehrm
mysql:8.0

If both containers are up, your deployment is successful.

Open OrangeHRM

Open your browser.
http://localhost:8080 (opens in a new tab)

The OrangeHRM Setup Wizard appears.

Installation Wizard

Step 1 — Fresh Installation
Choose: ✔️ Fresh Installation

Click Next.

Step 2 — License Agreement
Read the license.
Tick it. ☑️ I accept the terms in the License Agreement

Click Next.

Database Configuration

This is where many beginners encounter problems.

Since Docker already created the database, choose:
✔️ Existing Empty Database

Use the following values.

Uncheck

Use the same Database User for OrangeHRM

Then enter:

Why Use the Root User?

The installer must create:
• Tables
• Views
• Indexes
• Stored data

A normal database user cannot always perform these tasks.

Therefore:

Installer
↓
Uses root
↓
Creates OrangeHRM
↓
Application uses orangehrm user

This follows the security principle of least privilege.

Enable Data Encryption?

Many new users ask whether they should enable encryption during installation.

Development Environment
If you are:
• Learning OrangeHRM
• Testing features
• Creating sample employee records

If all the options are Yes, leave it disabled.

Why?
• Easier troubleshooting
• Simpler development
• No encryption key management

Production Environment 

If deploying for an organization with real employee information:

Enable encryption.

Also implement:
• HTTPS
• Secure passwords
• Regular backups
• Restricted database access
• User permissions
• Monitoring

Encryption is one part of a comprehensive security strategy.

Common Installation Errors

Error

Access denied for Privileged Database User

Cause
Using:
orangehrm
instead of
root

Solution
Use: 
Username
root
Password
rootpassword

Error

Database Already Exists

This simply means Docker has already created the database.

If the database contains no tables, select
Existing Empty Database

If you need a completely clean installation:
docker compose down -v
docker compose up -d

The -v option removes the MySQL volume and recreates an empty database.

System Check
OrangeHRM verifies:
✔️ PHP
✔️ Apache
✔️ MySQL
✔️ File permissions
✔️ cURL
✔️ OpenSSL
✔️ LDAP
✔️ GD
✔️ Zip
If everything is green, click Next.

Instance Creation

Enter your organization details.

Example:

Organization
XYZ (YOUR ORGANISATION NAME)
Country
Kenya
Language
English
Timezone
Africa/Nairobi

Administrator Account

Create the administrator.
Example: 
Username (YOUR NAME)
Choose a strong password.
sdwytefw (Your Password)

Confirmation

Review your configuration.
Example:
Host
db
Database
orangehrm
Admin (YOUR NAME)

Click → Install

Installation

OrangeHRM performs:
• Database creation
• Schema installation
• Configuration generation
• Administrator creation

Installation normally finishes within one minute.

Login
After installation.
Visit: http://localhost:8080 (opens in a new tab)
Login with your administrator account.

Congratulations! You now have a fully functional self-hosted HRIS.

Managing OrangeHRM 
Start : docker compose up -d
Stop : docker compose down
Restart : docker compose restart
View logs : docker compose logs -f
Application logs : docker logs orangehrm
Database logs : docker logs orangehrm-db

Backup the Database

Create a backup.
docker exec orangehrm-db mysqldump -uroot -prootpassword orangehrm > orangehrm_backup.sql
Restore.
docker exec -i orangehrm-db mysql -uroot -prootpassword orangehrm < orangehrm_backup.sql

Takeaways

Deploying OrangeHRM with Docker is one of the simplest and most reliable ways to set up a self-hosted Human Resource Management System (HRMS). Instead of manually configuring Apache, PHP, MySQL, and their dependencies, Docker provides a consistent environment that can be deployed, maintained, and upgraded with minimal effort.

Throughout this guide, you have learned how to:
• Install OrangeHRM using Docker Compose.
• Configure a MySQL database.
• Complete the OrangeHRM installation wizard.
• Troubleshoot common installation issues.
• Manage your containers.
• Back up and restore your database.

Once your installation is complete, you have a solid foundation for exploring OrangeHRM’s core modules, including employee management, leave management, recruitment, performance management, reports, and organizational administration.

As your environment grows, you can further enhance your deployment by implementing:
• HTTPS with a reverse proxy such as Nginx or Traefik.
• Automated database backups.
• Docker health checks.
• Monitoring and logging.
• Role-based access control.
• Secure password management.
• Regular image updates.

These improvements help transform a basic development installation into a production-ready deployment.

What’s Next?

Now that OrangeHRM is running successfully, you can continue expanding your knowledge by exploring topics such as:
• Configuring departments and organizational structures.
• Managing employee records.
• Setting up leave types and approval workflows.
• Using OrangeHRM’s REST API.
• Integrating OrangeHRM with workflow automation platforms.
• Deploying OrangeHRM behind a reverse proxy with HTTPS.
• Automating backups and updates.

These topics will be covered in future articles.

Thank you for Reading!

I hope this guide helped you successfully deploy OrangeHRM using Docker.

If you found this tutorial useful, consider following my future articles where I’ll share practical guides on:
• HR technology
• Workflow automation
• Docker
• Self-hosted applications
• Human Resource Information Systems (HRIS)
• Artificial Intelligence in business processes

Happy learning and happy building!