[GUIDE] How to get ERPNext running on UnRaid with Docker Compose

[p0p]

 Hi,

 

I'm very new to Docker and this is my second time to add Containers with Docker Compose. If there are improvements, please let me know 🙂

Currently running on: UnRaid 6.11.5

Used Docker Container: https://github.com/frappe/frappe_docker

Used and edited Compose file: https://github.com/frappe/frappe_docker/blob/main/pwd.yml 

 

Requirements:

UnRaid

Access to the Internet

Community Apps

Community App:

- Docker Compose

- Docker Folder

Specs:

- at least 4GB of RAM

- 10 GB disk space

 

Steps:

1. Have the Community Apps Extension installed.
2. Search inside the Community Apps for "Docker Compose" and "Docker Folder" and install the Apps.
3. Switch to the Docker Tab, you'll see a new Section for Compose,
4. At the Compose Section, on the most bottom left, click the Button "Add New Stack" - a Popup will appear.
5. Give your Stack a name, in this Case "erpnext"
6. Give your Stack a path, in this case 

   /mnt/user/appdata/erpnext

7. hit OK - Inside the Compose Section, you're going to see your new created stack.
8. Left of the Name of the stack "erpnext" hit the gear (option) icon - a popup will appear right above the name.
9. Hit "Edit Stack" - a popup will appear in the center of the screen.
10. Hit "Compose File" - the popup will close itself and a text editor will appear (you might have to scroll down a bit).
11. Delete the content inside the text editor. (e.g. "services:")
12. Add these lines

version: "3"

services:
  backend:
    image: frappe/erpnext-worker:v14.9.0
    container_name: backend
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - assets:/home/frappe/frappe-bench/sites/assets

  configurator:
    image: frappe/erpnext-worker:v14.9.0
    container_name: configurator
    command:
      - configure.py
    environment:
      DB_HOST: db
      DB_PORT: "3306"
      REDIS_CACHE: redis-cache:6379
      REDIS_QUEUE: redis-queue:6379
      REDIS_SOCKETIO: redis-socketio:6379
      SOCKETIO_PORT: "9000"
    volumes:
      - sites:/home/frappe/frappe-bench/sites

  create-site:
    image: frappe/erpnext-worker:v14.9.0
    container_name: create-site
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - assets:/home/frappe/frappe-bench/sites/assets
    entrypoint:
      - bash
      - -c
    command:
      - >
        wait-for-it -t 120 db:3306;
        wait-for-it -t 120 redis-cache:6379;
        wait-for-it -t 120 redis-queue:6379;
        wait-for-it -t 120 redis-socketio:6379;
        export start=`date +%s`;
        until [[ -n `grep -hs ^ common_site_config.json | jq -r ".db_host // empty"` ]] && \
          [[ -n `grep -hs ^ common_site_config.json | jq -r ".redis_cache // empty"` ]] && \
          [[ -n `grep -hs ^ common_site_config.json | jq -r ".redis_queue // empty"` ]];
        do
          echo "Waiting for common_site_config.json to be created";
          sleep 5;
          if (( `date +%s`-start > 120 )); then
            echo "could not find common_site_config.json with required keys";
            exit 1
          fi
        done;
        echo "common_site_config.json found";
        bench new-site frontend --admin-password=admin --db-root-password=admin --install-app payments --install-app erpnext --set-default;
  db:
    image: mariadb:10.6
    container_name: db
    healthcheck:
      test: mysqladmin ping -h localhost --password=admin
      interval: 1s
      retries: 15
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --skip-character-set-client-handshake
      - --skip-innodb-read-only-compressed # Temporary fix for MariaDB 10.6
    environment:
      MYSQL_ROOT_PASSWORD: admin
    volumes:
      - db-data:/var/lib/mysql

  frontend:
    image: frappe/erpnext-nginx:v14.9.0
    container_name: frontend
    deploy:
      restart_policy:
        condition: on-failure
    depends_on:
      backend:
        condition: service_started
      websocket:
        condition: service_started
    environment:
      BACKEND: backend:8000
      FRAPPE_SITE_NAME_HEADER: frontend
      SOCKETIO: websocket:9000
      UPSTREAM_REAL_IP_ADDRESS: 127.0.0.1
      UPSTREAM_REAL_IP_HEADER: X-Forwarded-For
      UPSTREAM_REAL_IP_RECURSIVE: "off"
    volumes:
      - sites:/usr/share/nginx/html/sites
      - assets:/usr/share/nginx/html/assets
    ports:
      - "6363:8080"

  queue-default:
    image: frappe/erpnext-worker:v14.9.0
    container_name: queue-default
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - default
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - assets:/home/frappe/frappe-bench/sites/assets

  queue-long:
    image: frappe/erpnext-worker:v14.9.0
    container_name: queue-long
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - long
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - assets:/home/frappe/frappe-bench/sites/assets

  queue-short:
    image: frappe/erpnext-worker:v14.9.0
    container_name: queue-short
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - short
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - assets:/home/frappe/frappe-bench/sites/assets

  redis-queue:
    image: redis:6.2-alpine
    container_name: redis-queue
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-queue-data:/data

  redis-cache:
    image: redis:6.2-alpine
    container_name: redis-cache
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-cache-data:/data

  redis-socketio:
    image: redis:6.2-alpine
    container_name: redis-socketio
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-socketio-data:/data

  scheduler:
    image: frappe/erpnext-worker:v14.9.0
    container_name: scheduler
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - schedule
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - assets:/home/frappe/frappe-bench/sites/assets

  websocket:
    image: frappe/frappe-socketio:v14.17.1
    container_name: websocket
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - assets:/home/frappe/frappe-bench/sites/assets

volumes:
  assets:
  db-data:
  redis-queue-data:
  redis-cache-data:
  redis-socketio-data:
  sites:

and hit Save at the top center of the text editor - A popup for "Edit Stack UI Labels" will appear

Enter the following for the services

Service: frontend

Icon - https://raw.githubusercontent.com/frappe/erpnext/develop/erpnext/public/images/erpnext-logo.png
Web UI - http://[IP][PORT:6363]/
Shell - leave as it is

Deploying the Application

1. In the column "Commands" hit "Compose Up" to start the deployment - It will create the Docker Containers required to run the application. The Docker Containers are going to start themselves.
2. Grab a Coffee, the initial process can take a while until ERPnext is up (depends on your machine).
3. Wait around 4 minutes for background processes to be finished
4. Navigate to http://YOURSERVERIP:6363 (replace YOURSERVERIP with the IP address of UnRaid server) // if this isn't working, try http://YOURSERVERIP:6363/app/setup-wizard/0 - The login mask should appear.
5. Login to the ERPnext Dashboard, use the following login information:

Fixing ERPNext PDF output / exports are not working (required step!)

1. Open the Terminal to your UnRaid server over SSH or over the web interface (">_" button on the top right)
2. enter this line to move to your erpnext folder

   cd /mnt/user/appdata/erpnext

3. ((This step is mentioned here on GitHub))
   to get vi (a texteditor) running and to edit "common_site_config.json" copy ALL the lines and paste it into the command line

   docker run --rm -it \
       -v erpnext_sites:/sites \
       alpine vi /sites/common_site_config.json

   Note: erpnext is the projectname (look at the line -v erpnext_sites:...) - replace it with your project name. If you've named it "superdupererp", enter that in here.
   
   The vi editor is now opened inside the command line.

4. hit "i" (for insert)  on your keyboart to enter the editing mode of vi

5. after the curly bracket "{"
   write the following line to add the IP-Address (or web-address if you want to expose ERPNext to the internet) and the port

   "host_name":"YOURSERVERIP:PORTNUMBER",

   (example: "host_name": "192.168.178.55:6363", )

6. Hit ESC on your keyboard

7. to safe and quit enter
   :wq
   or
   hit shift + ZZ

8. that's it

 

Default Login info:

Login:

http://YOURSERVERIP:6363

Default User:
Administrator
Default Password:
admin

 

Done - Setup ERPnext as you wish 

 

Docker Folders

You can use the CA Plugin Docker Folders to

• group your containers for a better overview
• add actions like run/stop
• add bash scripts

Notes:

Portmapping notes

Port 6363 is for the frontend  and a port set by me - you can set it to whatever port number you want.

Docker-Compose.yml notes

The UnRaid Docker Compose creates docker container in the following patterns:
{stack_name}{containername}{upcountingnumber}
example: "erpnext-frontend-1"

I've added some lines with "container_name: CONTAINER" to suppress this behavior. It seems like the lines are needed that the containers can actually communicate with each other.  

 

Troubleshooting

I can't get the application running

1. Check the logs (click on the docker container icon and on logs)
2. Check the docker-compose.yml file. Have you added spaces or something else there?
3. Check if you're using the same ports [inside the same docker network] for a docker container. Often the standard MySQL /MariaDB database port could be a culprit.
4. Ask questions on the applications GitHub/support forum

How to clear / bypass  Docker Compose Cache in Unraid - for a project

If somethings gone wrong while deploying or you broke something inside the application that isn't fixable, you need to fetch new Docker Container due to cached versions of the docker files:

1. Open the Terminal to your UnRaid server over SSH or over the web interface (">_" button on the top right)
2. WARNING: The following action deletes all the content of your application!
   
   enter line by line

   cd /mnt/user/appdata/erpnext
   
   docker-compose down --remove-orphans -v --rmi all
   
   docker-compose down && docker-compose build --no-cache && docker-compose up

    

3. Your containers should get re-downloaded and rebuild now (again coffee time!)

Known Issues and possible fixes  - Help is appreciated! 

• Connection aborts to the Database - The application is running fine, every action is stored. Seems to be a bug.
• Error Message "Support Email Address not specified" while setting up things in the ERPnext backend - haven't figured out where site_config.json file is to change the support mail to satisfy the little beasty message
  
  Possible fix: 
  Same steps as mentioned above "Fixing ERPNext PDF output / exports are not working (required step!)",
  just add

  “error_report_email”: "[email protected]",

  You can add your own email adress here if you wish. (you need to setup an email service like over SMTP to receive error mails)

• is_your_company_address could appear while setting up your company address - haven't found a solution yet.
  • It COULD be the following error source:
    • Data leftovers from previous build
      • Afterfirst and initial build, I played around and wanted and wanted to reset the application.
        I tried to docker compose down and compose up to revert back to inital state.
        But I haven't used the steps in the Troubleshooting section (found out about it later - scroll up a bit). 
        It could be that leftovers from the previous build have set "is_your_company_address" to the company address form.
        
        Possible fix: 
        Backup things. (For example over the "CA Backup" app
        Use the commands from the troubleshooting section.
    • Changed company address while using the introduction guide
      • I've entered the company address form WHILE using the introduction guide where you get guided through the application features. 
        
        Possible fix:
        Don't change your company address while you're in the introduction guide.

 

Happy ERPing!

Edited December 6, 2022 by p0p
added new knowledge

[p0p]

--- Room for Notes ---

[Rolucious]

Wow that was much easier than I initially expected when I red the documentation. Thank you for the help!

[JQNorman]

ran through the setup process and came across an access error to the db? any suggestions?

[vincent4]

On 1/11/2023 at 5:25 AM, JQNorman said:

ran through the setup process and came across an access error to the db? any suggestions?

hello friends, 

firsteal man thanks for this guide it helps me to install erp on my unraid. i hav modify a bit the script and mayby it will be helpfull for you  @JQNorman 

I use my early installeted mariadb container for this. 

 

After docker-compose up open frontend container and install erpnext by following command

bench --site frontend install-app erpnext

 

that it!

 

PS: and you need standard .env with you DB parametern

 

version: "3"

services:
  backend:
    image: frappe/erpnext:v14.14.0
    container_name: backend
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  configurator:
    image: frappe/erpnext:v14.14.0
    container_name: configurator
    entrypoint:
      - bash
      - -c
    command:
      - >
        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_SOCKETIO";
        bench set-config -gp socketio_port $$SOCKETIO_PORT;
    environment:
      DB_HOST: ${DB_HOST}
      DB_PORT: ${DB_PORT}
      REDIS_CACHE: redis-cache:6379
      REDIS_QUEUE: redis-queue:6379
      REDIS_SOCKETIO: redis-socketio:6379
      SOCKETIO_PORT: "9000"
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  create-site:
    image: frappe/erpnext:v14.14.0
    container_name: create-site
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs
    entrypoint:
      - bash
      - -c
    command:
      - >
        wait-for-it -t 120 redis-cache:6379;
        wait-for-it -t 120 redis-queue:6379;
        wait-for-it -t 120 redis-socketio:6379;
        export start=`date +%s`;
        until [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".db_host // empty"` ]] && \
          [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_cache // empty"` ]] && \
          [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_queue // empty"` ]];
        do
          echo "Waiting for sites/common_site_config.json to be created";
          sleep 5;
          if (( `date +%s`-start > 120 )); then
            echo "could not find sites/common_site_config.json with required keys";
            exit 1
          fi
        done;
        echo "sites/common_site_config.json found";
        bench new-site frontend --admin-password=admin --mariadb-root-password <ROOT_PASSWORD> --install-app payments --install-app erpnext --set-default;

  frontend:
    image: frappe/erpnext:v14.14.0
    container_name: frontend
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - nginx-entrypoint.sh
    environment:
      BACKEND: backend:8000
      FRAPPE_SITE_NAME_HEADER: frontend
      SOCKETIO: websocket:9000
      UPSTREAM_REAL_IP_ADDRESS: 127.0.0.1
      UPSTREAM_REAL_IP_HEADER: X-Forwarded-For
      UPSTREAM_REAL_IP_RECURSIVE: "off"
      PROXY_READ_TIMOUT: 120
      CLIENT_MAX_BODY_SIZE: 50m
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs
    ports:
      - "6363:8080"

  queue-default:
    image: frappe/erpnext:v14.14.0
    container_name: queue-default
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - default
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  queue-long:
    image: frappe/erpnext:v14.14.0
    container_name: queue-long
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - long
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  queue-short:
    image: frappe/erpnext:v14.14.0
    container_name: queue-short
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - short
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  redis-queue:
    image: redis:6.2-alpine
    container_name: redis-queue
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-queue-data:/data

  redis-cache:
    image: redis:6.2-alpine
    container_name: redis-cache
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-cache-data:/data

  redis-socketio:
    image: redis:6.2-alpine
    container_name: redis-socketio
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-socketio-data:/data

  scheduler:
    image: frappe/erpnext:v14.14.0
    container_name: scheduler
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - schedule
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  websocket:
    image: frappe/erpnext:v14.14.0
    container_name: websocket
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - node
      - /home/frappe/frappe-bench/apps/frappe/socketio.js
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

volumes:
  redis-queue-data:
  redis-cache-data:
  redis-socketio-data:
  sites:
  logs:

 

[Rouxlas]

Thank you very much!

 

I struggled a lot to get ERPnext running and this guide just worked perfectly on first try!

 

I have 2 questions maybe you can answer.

1) I can see 12 new dockers now all related to erpnext. Was that supposed to happen? I set all except of "configurator" to "autostart".

2) How should I go about updating this erpnext installation to the newest version?