Note: If you have already done the below install and got your environment up and running, here are the instructions to remember for "re-starting-up" your development environment after you've shut it down. Restart Dev Environment

This short instruction explains how to get your Mac OS X machine to be a development platform for Frappe and ERPNext as well as showing how to install Frappe in Developer Mode.

This gives you more control about what is happening but is harder than the installer. However this is setting up a development framework rather than a quick test of frappe framework. So if you want to try out ERPNext development maybe consider the vagrant file or the automated setup, if you want a real development machine, consider this tutorial.

You are highly recommended to start with a fresh machine here unless you are a mac wizard in which case you won't need this instruction to begin with...

This works best with a clean setup / install.

Any development on a Mac starts with a Homebrew install.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

(check the brew.sh homepage for the latest script). Homebrew will also install XCode Command Line Tools. If you are unable to install it via the homebrew script, you can download command line tools from the Apple Developer Website

https://developer.apple.com/download/more/

MacOS (upto 10.4) comes with Python 2 as the default, so its best to install Python 3, which is the latest and greatest python

brew install python

Troubleshooting: Homebrew Error and Installation of Python 3

Depending on if you had installed either Homebrew or Python in the past you may be missing a few folders. You'll need to create them and set their permissions.

sudo mkdir -p /usr/local/Frameworks /usr/local/sbin
sudo chown -R $(whoami) /usr/local/Frameworks /usr/local/sbin

Even though Python 3 may be installed, you may also need to link it properly.

brew link python

Frappe requires MariaDB as the default database backend and Redis for caching.

brew install mariadb redis

Start MySQL by

mysql.server start

Setup your default MariaDB passwords using the mysql_secure_installation utility. Just follow the prompts to set your default root password

sudo mysql_secure_installation

Frappe (version 11) uses Node v10 so you can manage your node installs using the awesome Node Version Manager (nvm)

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
nvm install v10 (or greater)

brew install yarn

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. Note: the following path may not necessarily be where your my.cnf file is. Type mariadb --help to find where yours is located.

nano /usr/local/etc/my.cnf 

Required code:

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

Optional: To keep your user folder clean, it is a good practice to create a development folder first:

mkdir Dev
cd Dev

Install bench via pip3.

pip3 install frappe-bench

Create a virtual environment for Bench (Python 3) so that it does not interfere with the default Python install that comes with MacOS (Python 2.7)

If you don't have virtualenv installed do so by running

pip3 install virtualenv

python3 -m venv bench-env
source bench-env/bin/activate
sudo pip install -e bench-repo

Note: You will have to activate bench-env every time you want to use the bench command. See Restarting Dev Environment

We can create different Bench installations to host different versions of the Frappe and ERPnext software. For our first bench, we will name it "frappe-bench". Note: you may run into errors with a package called psycopg2. Refer to the following discussion for a solution.

bench init frappe-bench --python /usr/local/bin/python3
cd frappe-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:

bench start

As Bench starts up, you will see many colorful lines of code, (oooooo!!!!) as your terminal window becomes a watcher for your running Bench.

Note that bench start starts all the processes that might need to be interacted with by other services, and it's a background watcher task. This means you may think it's "stuck" and waiting for next steps, but it's probably just waiting for you to interact with the browser, or for any process to start. Subsequent commands, such as bench update require bench start to be running.

NOTE: This tab is now ONLY for your running development instance of Bench. To proceed with the below steps, we will use a new tab.

NOTE: To shut down Bench, ONLY use ctrl-c. DO NOT CLOSE THE TAB RUNNING BENCH MANUALLY as it may cause errors requiring you to restart your computer in order to restart Bench later.

command-t on a mac

With 2 tabs open, one running Bench and our new tab, we will use our new tab to create our new site. From inside our new tab in our frappe-bench folder

bench new-site site1.local

If you have made a site in the past or you tried and it failed, you may get an error claiming the database already exists:

bench/apps/frappe/frappe/database/mariadb/setup_db.py”, line 43, in setup_database
   raise Exception(“Database %s already exists” % (db_name,))
Exception: Database _1bd3e0294da19198 already exists

To fix this, we will need to retry the command with the --force parameter added:

bench new-site site1.local --force

NOTE: Assuming this is your first site, it is also treated as your "default" site, and we can ignore certain flags that later may become required as you add additional sites. You can also change your default site later if you would like.

You may also get this error:

ERROR 1171 (42000) at line 232: All parts of a PRIMARY KEY must be NOT NULL; if you need NULL in a key, use UNIQUE instead

The solution is to update the query per this post: https://discuss.erpnext.com/t/solved-all-parts-of-a-primary-key-must-be-not-null-on-mysql-5-7/52886/3. The steps are:

• Edit frappe-bench/apps/frappe/frappe/database/mariadb/framework_mariadb.sql
• Update the query as follows

CREATE TABLE `tabSeries` (
  `name` varchar(100),
  `current` int(10) NOT NULL DEFAULT 0,
  PRIMARY KEY(`name`)
) ENGINE=InnoDB ROW_FORMAT=COMPRESSED CHARACTER SET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Note that the DEFAULT NULL suffix to the name field is deleted.

Note also, that this is fixed in a newer release of frappe, so you may not get this issue if you did a bench update.

bench get-app erpnext bench install-app erpnext will install ERPnext on the bench, meaning all sites will have access ERPnext apps. bench --site site1.local install-app erpnext only install it for a particular site.

Open up site_config.json and add the developer mode flag:

sudo nano sites/site1.local/site_config.json

Add "developer_mode": 1 inside of the brackets and leave the other information alone. Take care to make sure your commas are in the right place and there is no trailing comma on your last entry. Here is an example of what the contents of the file should look something like this (DO NOT change your db_name or db_password):

	{
	 "db_name": "1bd3e0294d", 
	 "db_password": "jfhgsdfjgh35h34j",
	 "developer_mode": 1
	}

Now save and exit that file.

To enable viewing your new local site in your browser, edit your host file

sudo nano /etc/hosts

Add the following, then save and close the file:

127.0.0.1 site1.local

For these and other major changes to take effect, we need to run bench update

bench update

TIP: As you develop, you will find bench update to be slow and unneeded at times and you can execute faster running commands such as bench migrate for updating data structure in frappe development changes and bench build for front end and JS file changes.

You may see an update issue and need to do a bench update reset command:

bench update --reset

You may run into an error for Yarn install. Currently, your best option is to designate what branch you are on.

bench switch-to-branch version-12 frappe erpnext
bench update --reset

If you still cannot run bench update without errors, chances are there is a rogue untracked file somewhere. Try this:

cd apps/frappe
git status

If you see an untracked file like this:

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	patches.txt

nothing added to commit but untracked files present (use "git add" to track)

Unfortunately, neither the bench update --reset git reset --hard or git stash commands that they recommend seem to work. So just remove it, and try running bench update again:

rm patches.txt
cd ../../
bench update

Navigate to URL: http://site1.local:8000/#login or http://localhost:8000

You may get errors in your browser if you go to http://localhost:8000 since frappe generally looks for the site-name to match the one configured in your hosts file. So use http://site1.local:8000 if you see any issues.

Been a while since you were developing or restarted your computer? You will notice bench commands no longer work. Here are the couple steps to get you back up and running:

mysql.server start # brew services start mysql in recent homebrew systems

From the command line, enter your dev folder...

Enter your Frappe project folder:

cd frappe

Launch the bench environment so bench commands work:

source bench-env/bin/activate

Enter your project init folder, yours maybe named different than the default:

cd frappe-bench

Now you can run Bench commands from the frappe-bench folder without problems.

Start up your site:

bench start

Open another tab or window to run follow up bench commands, and remember to close Bench down properly from the Bench verbose running tab with ctrl+c command.

Open your browser and enjoy:

Navigate to URL: http://site1.local:8000/#login.