How to install HRMS in docker version?

miljan23 · June 5, 2023, 7:23am

Hello all,
i am pretty new to ERPNext, i will like if anyone has a full guide how to install ERPNext with HRMS module also.

Thank you in advance

revant_one · June 5, 2023, 7:26am

Arvind_Das · December 13, 2023, 3:49pm

Hi Everyone ,

Here is a custom image for the same , the image is prebuilt with hrms and payroll modules.

This should make things easy for everyone since many users are looking for the same.

This image is built on branch v15

trustedcomputer · December 13, 2023, 3:57pm

This is a bit off-topic, but could you comment on your use of the mariadb:11.2 instead of 10.6? Have you been using this for some time, and does it work well without problems? What about 10.11? Thanks!

Arvind_Das · December 13, 2023, 4:11pm

To be true, this is my first installation of ERPNext.

I could read somewhere in the documentation that version 11 of Mariadb should work as well so wanted to give it a try.
I am evaluating ERPNext right now and testing out all the features. I will comment here if I find something failing with v11 of Mariadb. I can surely go for 10.6 but will only fallback if some issue comes up with 11. Could you suggest me the flows which might fail ( that will help me test those first) .

trustedcomputer · December 13, 2023, 4:14pm

I can not. I’ve always stuck to 10.6 since that’s what’s used in the frappe_docker repository. So I don’t know if using 11 might have some compatibility issues. I know 10.6 and 10.11 are both LTS releases of mariadb, so personally I would stick with one of those for long-term stability.

Arvind_Das · December 13, 2023, 4:20pm

Ah! I see that , v11 is only supported till June 2024, probably I should go back , I will test things out since it will take some time to enter the values again. But moving to 10.6 seems to be the right way.

morphious · December 27, 2023, 11:11am

Hi,

First of all thank you for the custom image, I was trying to do the same, installing erpnext, bench and hrms apps using custom apps.json to build my custom image.

Can you update your readme.md on how did you built this custom image. I’ve been trying to use version-15 for bench, erpnext and hrms but hrms app post installation would blow out.

Also, Have you ported back to v10.6 for mariadb? Also, how do we set it up for production use case, with backups?

Thanks again.

Arvind_Das · January 1, 2024, 4:13pm

Hi @morphious

I have added my apps.json that I am using.

The link at https://github.com/vibeconn/erpnext-custom/blob/main/README.md has been updated.

The issue I faced was the installation would get cancelled due to network errors and pulling of resources during build time, so make sure your internet is stable(better build at a remote EC2 instance) .
The custom Image was built using the standard documentation here at https://github.com/frappe/frappe_docker/blob/main/docs/custom-apps.md

Yes, I have ported back to v10.6 since it is a stable LTS version. I did not have any issues with v11 but for production use I ported to 10.6 since this is a tested one by the team.

For backups, currently I see there are issues with AWS S3 backups, but Google Drive backup works well. You can use that . I would wait for S3 issue to resolve and then switch since with growing data, drive will not be the right option.

For use cases like scaling the backend/frontend, I have not tried that yet but should be easy to go with docker swarm , converting individual containers to services.(Needs Testing)

Arvind_Das · January 1, 2024, 4:43pm

Also, the S3 backup issue is resolved , S3 Backup Error (An error occurred (400) when calling the HeadBucket operation: Bad Request) - #3 by itanand
So you can use S3 for backups.

morphious · January 2, 2024, 6:12am

Makes sense. I have faced dependency pulling issue due to network errors a lot. Good suggestion, piggy backing over aws backbone network would help.

Alright, I’ll port to v10.6 for sure. S3 backups are for sure the best thing out there. We can have lot of control on our backups.

higguns · June 6, 2024, 12:46am

Is it possible to add the newer Print Designer app to this as well? I’m running this custom install image on portainer and can’t get Print Designer to install after using this custom install image. Any help would be appreciated!

anon67314007 · August 28, 2024, 9:21am

It says need dockerfile though.

anon67314007 · August 28, 2024, 9:35am

I’ve got this error after running this: docker build --build-arg=APPS_JSON_BASE64=$APPS_JSON_BASE64 --tag=custom/hrms:1.0.0 --file=images/custom/Containerfile .

ERROR: resolve : CreateFile images: The system cannot find the file specified.

anup · September 7, 2024, 7:12am

Did you clone the frappe_docker repo and changed into the frappe_docker directory. The container file is in the frappe_docker repo. I guess you missed running the command on the first line -
git clone GitHub - frappe/frappe_docker: Docker images for production and development setups of the Frappe framework and ERPNext && cd frappe_docker

rajv · September 15, 2024, 11:34am

Here are the steps that I use for production, although its pretty decently documented in the official docs and links already.

Clone the repo “GitHub - frappe/frappe_docker: Docker images for production and development setups of the Frappe framework and ERPNext” and cd frappe_docker.
Create a apps.json file there with the below info:

[
    {
      "url": "https://github.com/frappe/erpnext",
      "branch": "version-15"
    },

    {
      "url": "https://github.com/frappe/hrms",
      "branch": "version-15"
    }
]

Export above using this “export APPS_JSON_BASE64=$(base64 -w 0 /path/to/apps.json)”.
Then go ahead and make sure to copy and rename example.env to .env (I’m not using any external DB/components and I used override to use the compose for other components of frappe.
Now use this command to create a docker compose file from the template.

export CUSTOM_IMAGE='ghcr.io/user/repo/custom'
export CUSTOM_TAG='1.0.0'
docker compose -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.noproxy.yaml \
  config > ~/gitops/docker-compose.yaml

The 2 env variable are required to be able to replace the variables defined in compose.yaml.

After this step all you need to do is Docker build and your image build should complete,

docker build \
  --build-arg=APPS_JSON_BASE64=$APPS_JSON_BASE64 \
  --tag=ghcr.io/user/repo/custom:1.0.0 \
  --file=images/custom/Containerfile .

After the image is build make sure to push it using docker push

I’m still working on Binds but facing permission issues, once done I shall also share using BIND volumes to use folders on the HOST instead of docker volumes.(more on this later).
7. Now run docker compose to get the container up and running:

docker compose -f ~/gitops/docker-compose.yaml up -d

You can monitor the logs etc. in another terminal for the above in parallel.
Now the important bit is you MUST create a site and then install HRMS using bench command by logging into the backend container. I’m assuming logging into the container is not an issue or refer here: docker exec | Docker Docs

Site creation:  
a. bench new-site xyz.localhost
b. bench --site xyz.localhost install-app hrms  (This will install ERPnext and hrms, once done confirm they are installed.)
c. bench --site xyz.localhost list-apps

In the above setup I use my own certificate manager and reverse proxy, when I use "
-f overrides/compose.https.yaml" it causes issues with Traefik/cert issues etc for me.
For certificates and reverse proxy I use certbot and nginx.

I want also like to emphasize @revant_one and Frappe’s team has done an excellent work in terms of documentation. Also @revant_one thanks a TON for all the active support & help!!! Thankyou guys.

I’m a noob at ERPNEXT, if in case there are issues with the process that I’m following please feel free to call them out. It would really help in rectifying things at my end and for others who might use this post.

tealstream · October 3, 2025, 7:51pm

First I want to thank @rajv for putting together the above post. It was very helpful for me. And for @revant_one for being the source of a lot of it.

I know this is an old post but I could not find many good docs summarizing this process for a new/noobie user like myself.

Here’s a markdown of my notes, building off of the post above. The only real change is that I adjusted the configurator commands due to a front-end build issue that arose, and just included the install-app hrms in there instead of doing it post container startup like @rajv above.

I hope this helps someone in the future.

Building Custom ERPNext Docker Image

Use this process when updating the container, adding custom apps, or changing infrastructure within the docker stack.

Prerequisites

Docker and Docker Buildx installed
Access to ghcr.io/tealstream/tealerp registry
Clone of frappe_docker repo

Part 1: Build Custom Image

1. Clone frappe_docker (if starting fresh)

git clone https://github.com/frappe/frappe_docker
cd frappe_docker

2. Create apps.json

Create the apps configuration file in the frappe_docker folder:

cat > apps.json << 'EOF'
[
    {
      "url": "https://github.com/frappe/erpnext",
      "branch": "version-15"
    },
    {
      "url": "https://github.com/frappe/hrms",
      "branch": "version-15"
    }
]
EOF

3. Encode apps.json to base64

macOS:

export APPS_JSON_BASE64=$(base64 -i apps.json)

Linux:

export APPS_JSON_BASE64=$(base64 -w 0 apps.json)

4. Build and push the image

Update version tag as needed (e.g., 1.0.0 → 1.0.1). This takes many minutes (20+) to build and push.

docker buildx build \
  --build-arg=APPS_JSON_BASE64=$APPS_JSON_BASE64 \
  --tag=ghcr.io/tealstream/tealerp/erpnext-custom:1.0.0 \
  --file=images/custom/Containerfile \
  --platform linux/amd64 \
  --push \
  .

Note: The --push flag pushes automatically, so no separate docker push needed.

Part 2: Generate Docker Compose Configuration

1. Prepare .env file

Either:

Rename example.env to .env and configure it, OR
Use backup: ~/tealerp/config-backups/.env

Key .env settings:

FRAPPE_SITE_NAME_HEADER=frontend (must match existing site)
HTTP_PUBLISH_PORT=8080
DB_PASSWORD=123

2. Modify compose.yaml

Use the backup from ~/tealerp/config-backups/compose.yaml or modify these sections:

Add to configurator environment:

services:
  configurator:
    environment:
      DB_HOST: ${DB_HOST:-}
      DB_PORT: ${DB_PORT:-}
      REDIS_CACHE: ${REDIS_CACHE:-}
      REDIS_QUEUE: ${REDIS_QUEUE:-}
      SOCKETIO_PORT: 9000
      FRAPPE_SITE_NAME_HEADER: ${FRAPPE_SITE_NAME_HEADER:-frontend}  # Match your site name. Required for build command within container, otherwise the bash command inside the container wouldn't have access to the variable, even though .env contains it.

Update configurator command:

    command:
      - >
        ls -1 apps > sites/apps.txt;
        bench set-config -g db_host $$DB_HOST;
        bench set-config -gp db_port $$DB_PORT;
        bench set-config -g redis_cache "redis://$$REDIS_CACHE";
        bench set-config -g redis_queue "redis://$$REDIS_QUEUE";
        bench set-config -g redis_socketio "redis://$$REDIS_QUEUE";
        bench set-config -gp socketio_port $$SOCKETIO_PORT;
        bench --site $$FRAPPE_SITE_NAME_HEADER build;  # Build assets to prevent frontend errors. Unclear why I got these errors but front-end was displaying like a 1992 website before I rebuilt and restarted the container.
        bench --site $$FRAPPE_SITE_NAME_HEADER install-app hrms;  # Install HRMS app

3. Generate final docker-compose.yaml

Set environment variables to match your new image version:

export CUSTOM_IMAGE='ghcr.io/tealstream/tealerp/erpnext-custom'
export CUSTOM_TAG='1.0.0'

docker compose -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.noproxy.yaml \
  config > ~/tealerp/docker-compose.yaml

Part 3: Deploy

1. Start the stack

cd ~/tealerp
docker compose down  # Stop existing containers
docker compose up -d

2. Verify deployment

Open browser to: http://localhost:8080 or http://frontend:8080

Login with your existing credentials.

Important Notes

Data Persistence

All data persists in Docker volumes regardless of image version:

Transactions
User data
Configuration
Databases

Critical: The .env file’s FRAPPE_SITE_NAME_HEADER must match your existing site name (e.g., frontend) to maintain data continuity.

Troubleshooting

Frontend CSS/JS errors (404s)?

Assets may not have built properly
Restart frontend: docker restart frappe_docker-frontend-1
Or manually build: docker exec -it frappe_docker-backend-1 bench --site frontend build

Site not found?

Check FRAPPE_SITE_NAME_HEADER matches your site name
Verify site exists: docker exec -it frappe_docker-backend-1 ls sites/

Version History

Version	Date	Changes
1.0.0	YYYY-MM-DD	Initial version with HRMS
1.0.1	YYYY-MM-DD	[Description]