I’ve been exploring ERPNext a fair bit this week and have been impressed with the features, design and flexibility it offers.

In my effort to further use the platform, I’ve decided to install it on my MacOS for faster experimentation and utilization.

Here are the steps I follow to get ERPNext installed on my MacOS.

Install Pre-requisites

Install nodejs

# use the n version manager
n 12

Install yarn

npm install -g yarn

Install MariaDB

Follow instructions at: /install-and-secure-mariadb-on-macos-catalina.md Password for root: santa123

Install Redis

brew install redis
brew info redis

brew services start redis
brew services list

Setup MariaDB config for ERPNext in my.cnf Open my.cnf and add or make sure there is the following required code. You can use nano or whatever editor is installed like atom.

subl /usr/local/etc/my.cnf Required code (my exact file is):

refer: https://stackoverflow.com/questions/766809/whats-the-difference-between-utf8-general-ci-and-utf8-unicode-ci/766996#766996

# This group is read both by the client and the server
# use it for options that affect everything

# include *.cnf from the config directory
!includedir /usr/local/etc/my.cnf.d

character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

default-character-set = utf8mb4
# restart mariadb
brew services stop mariadb
brew services restart mariadb

brew services list

To check the start config:

subl ~/Library/LaunchAgents/homebrew.mxcl.mariadb.plist

Install Frappe Bench

Let’s follow the steps followed in this post: The Hitchhiker’s Guide to Installing Frappe on Mac OS X · frappe/frappe Wiki

pip install frappe-bench

I ran into the below errors, that I fixed with the following commands:

ERROR: pytest-astropy 0.8.0 requires pytest-cov>=2.0, which is not installed.
ERROR: pytest-astropy 0.8.0 requires pytest-filter-subpackage>=0.1, which is not installed.
ERROR: astroid 2.3.3 requires typed-ast<1.5,>=1.4.0; implementation_name == "cpython" and python_version < "3.8", which is not installed.
pip install pytest-filter-subpackage
pip install pytest-cov
pip install pytest-astropy

Just to make sure, I installed frappe-bench again:

pip install frappe-bench

Everything went fine:

bench --version
Check Bench Version
Check Bench Version

Initiate a new Bench Instance

For our first bench, we will name it “frappe-bench”.

bench init frappe-bench

You should end-up with a message saying:

SUCCESS: Bench frappe-bench initialized

Frappe bench successfully installed!
Frappe bench successfully installed!

Start up Bench

Since we are in a development (and not a production) environment we will need to start-up and shut-down Bench manually. In a production mode, we would use Nginx and other apps to keep it running at all times:

Let’s fire up tmux and start bench

cd frappe-bench
bench start

You should see a lot of colored messages showing that bench has started and is alive!

Frappe bench alive and kicking!
Frappe bench alive and kicking!

Create a New Frappe Site

Let’s open a new pane in tmux. From inside the new pane in our frappe-bench folder, lets create a new site:

cd frappe-bench

# lets specify a good db name too!
# credit: [User defined database name - Install / Update / Setup - Discuss Frappe/ERPNext](https://discuss.erpnext.com/t/user-defined-database-name/20030/3)

bench new-site erpnext.local --db-name erpnext-demo

# the new site should be in the sites folder
ls -al ./sites/

You will be asked to set the Administrator password for the new site! 1234 is a good choice locally! (ONLY! :-D)

Setup new site on frappe called erpnext.local
Setup new site on frappe called erpnext.local

Download and Install ERPNext into the site

# Get ERPNext app
bench get-app erpnext

# you should see erpnext app
ls ./apps
erpnext app added to frappe bench
erpnext app added to frappe bench

Installing Frappe Apps onto Sites

As mentioned here, lets add erpnext to our site erpnext.local

# Add the app to the site
bench --site erpnext.local install-app erpnext

Site based multi-tenancy

As mentioned here, Frappe lets you create multiple sites, in a single instance.

Use the text-editor of your choice (I’m using Sublime Text here) and add an entry of the site you just created into the /etc/hosts file.

sudo subl /etc/hosts

Add the following line and save the file erpnext.local

You’re all set!

Make sure that bench is running

bench start

Now you can simply access the site you just created using the link erpnext.local:8000

You should see your shiny new site up!

erpnext.local is live!
erpnext.local is live!

Setting up ERPNext

Login using Administrator and the password you used during the setup! After few initiation steps, you should see ERPNext in its full glory before you and your customers!

Erpnext In Full Glory!
Erpnext In Full Glory!

I strangely forgot my Administrator that I could set using:

# credit: [Reset admin password - ERPNext - Discuss Frappe/ERPNext](https://discuss.erpnext.com/t/reset-admin-password/22007/24)
bench --site [site] set-admin-password [new password]

Setting up Troubleshooting

Strangely, I always encountered the below startup error while doing the initiation steps.

erpnext startup setup error
erpnext startup setup error

Fortunately, the fix was pretty straightforward:

  • Restart bench
  • Go to http://erpnext.local:8000/#login
  • Restart the initiation process with EXACTLY the same details
  • Hit Retry a couple of times! (no idea why?)
  • Login again as the Administrator
  • Setup the Session Defaults with the company that was just provided in the initiation phase

Few Tips

In development and learning, using a simple password can speed up the process (although not advisable from a security viewpoint!).

The password policy can be relaxed from System Settings





Bench Manager

credit: Bench Manager

bench new-site bench-manager.local
bench get-app bench_manager https://github.com/frappe/bench_manager
bench --site bench-manager.local install-app bench_manager

Bench with NGINX

enable a site:

For enabling a site:

cd /usr/local/etc/nginx/sites-enabled
ln -s ../sites-available/erpnext.local

PDF Generation Installation requirements for ERPNext

openerp - How to install wkhtmltopdf patched qt without compiling? - Stack Overflow

Error when attempting to generate a PDF · Issue #6025 · frappe/erpnext

sudo wget -P Downloads https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.xenial_amd64.deb

cd ~/Downloads

sudo apt-get -f install wkhtmltox sudo apt-get install xfonts-75dpi

sudo dpkg -i wkhtmltox_0.12.6-1.xenial_amd64.deb

sudo cp /usr/local/bin/wkhtmltopdf /usr/bin

wkhtmltopdf -V