Frappe HR on Ubuntu 24.04 on Azure User Guide

Overview

Frappe HR is an open-source HR and payroll application built on the Frappe framework and ERPNext. It covers the employee lifecycle: employee records and onboarding, attendance and shift scheduling, leave policies, allocations and applications, expense claims and advances, salary structures and payroll processing, appraisals and goals, and recruitment, with the resulting entries posted into ERPNext's accounts.

Frappe HR declares ERPNext as a required application, so this image ships the complete ERPNext suite alongside it. The cloudimg image installs the whole stack as a full production deployment - MariaDB, Redis, a Python gunicorn web tier, background workers and a scheduler managed by supervisor, and nginx on port 80 - runs the entire headless install at build time so there is no command-line bootstrap on first use, builds the mobile progressive web app and the shift roster front ends that a manual install has to compile separately, and rotates the Frappe Administrator password, the site database password and the Frappe encryption key on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• Frappe HR v16.16.0 on ERPNext v16.31.1 and Frappe framework version-16, served on port 80 by nginx in front of a gunicorn web worker
• The Frappe HR mobile progressive web app at /hrms and the shift roster at /hr, both compiled and served
• Python 3.14 and Node.js 24, which Frappe version-16 requires
• MariaDB on loopback (Barracuda / utf8mb4 / large packets per Frappe), tuned for a small VM
• Redis for cache, queue and socketio; supervisor managing the Frappe web, worker and schedule processes
• The standard Frappe HR master data - leave types, expense claim types, employment types and salary components - seeded and ready
• A neutral starter company with a standard chart of accounts, so the HR module works the moment you sign in
• A unique Administrator password, site database password and Frappe encryption key generated on first boot, with no default login
• No employee, payroll or leave records pre-loaded - the system is empty and ready for your own data
• nginx.service, supervisor.service, mariadb.service and redis-server.service as systemd units, enabled and active
• 24/7 cloudimg support

A note on compliance

This image makes no compliance claims. Frappe HR as shipped here is not GDPR-compliant out of the box and is not a payroll-regulatory or tax-filing product. cloudimg ships the software installed, configured and hardened; how you use it for real employee data is yours to govern.

Because you will be entering employee personal data and, if you run payroll, financial data, you remain responsible for your own compliance posture. That includes establishing a lawful basis for processing, honouring data-subject rights, setting a retention and deletion policy, encrypting data in transit (see Enabling HTTPS) and at rest, restricting network access, managing user roles and permissions, keeping audit records, and meeting the payroll and tax obligations of your jurisdiction. Treat this VM as a system holding sensitive personal data from the moment you add your first employee.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B4ms (4 vCPU / 16 GiB RAM) is the recommended size and matches cloudimg's ERPNext and Frappe Lending images, because this appliance contains ERPNext. The stack is memory tuned and runs on a Standard_B2s (2 vCPU / 4 GiB RAM) for evaluation, but choose B4ms or larger for production HR and payroll workloads and multiple concurrent users. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web interface (front with TLS for public exposure - see Enabling HTTPS).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Frappe HR by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name frappe-hr \
  --image <marketplace-image-urn> \
  --size Standard_B4ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

Then open the web port:

az vm open-port --resource-group <your-rg> --name frappe-hr --port 80 --priority 900

Step 3 - Connect to your VM

ssh azureuser@<vm-ip>

Step 4 - Confirm the HR stack is running

All four services should report active:

systemctl is-active mariadb redis-server supervisor nginx

Frappe answers an unauthenticated health check, and both applications are installed on the site:

curl -s http://127.0.0.1/api/method/ping

Step 5 - Retrieve the Administrator password

Every VM generates its own Administrator password on first boot and writes it to a root-only file. Nothing is shared between deployments and there is no default login.

sudo cat /root/frappe-hr-credentials.txt

The file is readable only by root:

sudo stat -c '%a %U:%G %n' /root/frappe-hr-credentials.txt

The per-VM password authenticates while published vendor defaults are rejected, anonymous access to employee and payroll data is denied, and the HR module is proven working by a real Employee round-trip:

Step 6 - Sign in to Frappe HR

Browse to http://<vm-ip>/ and sign in as Administrator with the password from Step 5.

After signing in you land on the Frappe desk. Frappe HR does not use a single "HR" page - it organises the module into separate workspaces. Start at HR Setup:

http://<vm-ip>/app/hr-setup

The other HR workspaces are Tenure (/app/tenure), Recruitment (/app/recruitment), Leaves (/app/leaves), Expenses (/app/expenses), Performance (/app/performance) and Payroll (/app/payroll). You can reach them all from the sidebar once you are in any one of them.

Step 7 - Set up your company

The image ships a neutral starter company named Demo Company with a standard chart of accounts, so the HR module is usable immediately and you can evaluate it without any setup. It contains no employee, payroll or leave data.

For production use, either rename it or create your own:

• Rename: go to http://<vm-ip>/app/company, open Demo Company, and use Menu -> Rename to set your own legal entity name and abbreviation. Then set your country, default currency and fiscal year on the same form.
• Create a new company: from the same list choose Add Company, fill in the name, abbreviation, default currency and country, and pick a chart of accounts template. Set it as the default in Global Defaults.

Employees, salary structures, leave allocations and payroll entries are all scoped to a company, so make sure the company you intend to use exists before Step 8.

If you create a company for a different country, Frappe HR seeds that country's salary components automatically when the company is saved.

Step 8 - Add your first employee

The Employee record is the anchor of the whole system: leave, attendance, payroll, expense claims and appraisals all hang off it.

Go to http://<vm-ip>/app/employee and choose Add Employee. Enter the first name, select the company, gender, date of birth and date of joining, then save. The employee ID is generated from the HR-EMP- naming series.

To let an employee sign in and use self-service, create a User for them and link it in the User ID field on the employee record.

Step 9 - Configure leave

The image ships the standard leave types - Casual Leave, Sick Leave, Privilege Leave, Compensatory Off and Leave Without Pay. Review them at http://<vm-ip>/app/leave-type.

Before employees can apply for leave, allocate it. A Leave Policy (/app/leave-policy) groups leave types and annual amounts; a Leave Policy Assignment grants that policy to employees for a leave period; or allocate directly with a Leave Allocation (/app/leave-allocation). Employees then submit Leave Applications (/app/leave-application), which check the allocated balance and the company holiday list.

Create a Holiday List at /app/holiday-list for your working calendar and set it on the company or on individual employees.

Step 10 - Payroll

Payroll is driven by salary components and salary structures. The image seeds the standard salary components for the starter company's country; review them at http://<vm-ip>/app/salary-component.

Build a Salary Structure (/app/salary-structure) from earnings and deduction components, assign it to employees with a Salary Structure Assignment, then run a Payroll Entry (/app/payroll-entry) for a period to generate salary slips. Submitting the payroll entry posts the accounting entries into ERPNext.

Payroll rules, tax rates and statutory deductions vary by jurisdiction and are your responsibility to configure and verify - see the compliance note above.

Step 11 - The mobile progressive web app

Frappe HR ships a mobile-first progressive web app for employee self-service - checking in and out, applying for leave, submitting expense claims and viewing salary slips. It is built into this image and served at:

http://<vm-ip>/hrms

The shift roster interface is at http://<vm-ip>/hr.

Step 12 - Verify the HR module from the command line

The image ships a self-test that creates a real Employee, reads it back, and removes it again, and asserts the HR master data is present. It is the same check cloudimg runs against the published image, and it is safe to run at any time - it leaves no records behind:

sudo /usr/local/sbin/frappe-hr-selftest.sh

Step 13 - Enabling HTTPS

The image serves plain HTTP on port 80. Employee and payroll data is sensitive, so terminate TLS in front of the site before entering any real data. Install certbot and issue a certificate for a DNS name that points at the VM:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d hr.your-domain.example

Then tell Frappe its public URL so generated links use HTTPS:

sudo -u frappe -H bash -lc "cd /opt/frappe/frappe-bench && bench --site hr.localhost set-config host_name 'https://hr.your-domain.example'"
sudo systemctl restart supervisor

Open 443/tcp in the NSG and restrict 80/tcp to the redirect only.

Step 14 - Maintenance

Check the Frappe process tree:

sudo supervisorctl status

Back up the site (database plus files). Backups are written under the site's private/backups directory:

sudo -u frappe -H bash -lc "cd /opt/frappe/frappe-bench && bench --site hr.localhost backup"

Because these backups contain employee personal data, move them off the VM to encrypted storage and apply your retention policy to them.

Keep the operating system patched:

sudo apt-get update && sudo apt-get -y upgrade

Restart the application tier after configuration changes:

sudo systemctl restart supervisor && sudo systemctl reload nginx

Troubleshooting

The site does not respond on port 80. Confirm nginx and supervisor are active with systemctl is-active nginx supervisor, then check the Frappe processes with sudo supervisorctl status. Confirm the NSG allows inbound 80/tcp.

Sign-in fails. Re-read the password with sudo cat /root/frappe-hr-credentials.txt. The username is Administrator. There is no default password in this image; each VM generates its own on first boot.

First boot did not complete. Inspect the one-shot service with sudo systemctl status frappe-hr-firstboot.service and sudo journalctl -u frappe-hr-firstboot.service.

An employee record will not save. First name, company, gender, date of birth and date of joining are all mandatory, and the date of joining must be after the date of birth. If the gender list is empty, add entries at /app/gender.

A leave application is rejected for insufficient balance. Leave must be allocated before it can be applied for. Check /app/leave-allocation for that employee and leave type, and confirm the leave period covers the requested dates.

Payroll produces no salary slips. Every employee in the payroll entry needs an active Salary Structure Assignment covering the payroll period. Check /app/salary-structure-assignment.

Support

cloudimg provides 24/7 support for this image by email at support@cloudimg.co.uk and via live chat, with a one hour average response time for critical issues.

Frappe, ERPNext and Frappe HR are trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.