-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Setting up a Mac for Frappe ERPNext Development
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 pythonTroubleshooting: 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/sbinEven though Python 3 may be installed, you may also need to link it properly.
brew link pythonFrappe requires MariaDB as the default database backend and Redis for caching.
brew install mariadb redisStart MySQL by
mysql.server startSetup your default MariaDB passwords using the mysql_secure_installation utility. Just follow the prompts to set your default root password
sudo mysql_secure_installationFrappe (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 yarnOpen 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 DevInstall bench via pip3.
pip3 install frappe-benchCreate 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 virtualenvpython3 -m venv bench-env
source bench-env/bin/activate
sudo pip install -e bench-repoNote: You will have to activate
bench-envevery time you want to use thebenchcommand. 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-benchSince 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 startAs 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-ton 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.localIf 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 existsTo fix this, we will need to retry the command with the --force parameter added:
bench new-site site1.local --forceNOTE: 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.jsonAdd "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/hostsAdd the following, then save and close the file:
127.0.0.1 site1.localFor these and other major changes to take effect, we need to run bench update
bench updateTIP: As you develop, you will find
bench updateto be slow and unneeded at times and you can execute faster running commands such asbench migratefor updating data structure in frappe development changes andbench buildfor front end and JS file changes.
You may see an update issue and need to do a bench update reset command:
bench update --resetYou 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 --resetIf you still cannot run bench update without errors, chances are there is a rogue untracked file somewhere. Try this:
cd apps/frappe
git statusIf 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 updateNavigate 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 systemsFrom the command line, enter your dev folder...
Enter your Frappe project folder:
cd frappeLaunch the bench environment so bench commands work:
source bench-env/bin/activateEnter your project init folder, yours maybe named different than the default:
cd frappe-benchNow you can run Bench commands from the frappe-bench folder without problems.
Start up your site:
bench startOpen 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.
Custom Footer Page