This guide will walk you through the process of setting up Frappe/ERPNext for a development environment on Apple Silicon. Follow these steps carefully to ensure a smooth setup.
Prerequisites:
- Administrator Access: Some commands require administrative privileges.
- Terminal Application: All the commands provided should be executed in the Terminal.
1. Setting up the Environment as Administrator
For the following commands, you’ll need a user with administrative privileges.
1.1 Install Homebrew:
Homebrew is a package manager for MacOS, which allows you to install software packages easily.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
1.2 Allow homebrew for the non-admin user (optional)
If you want to run your bench as a non-admin user, it will need access to everything inside /opt/homebrew/. To get the exact commands, you can run brew doctor as the non-admin user, then execute them as the admin user.
2. Setting up the User Environment
The following commands can (mostly) be run as a normal, non-privileged user. If you want to setup ERPNext for the admin user, that’s fine as well.
2.0 (Optional) Install Oh-My-Zsh:
This enhances your terminal experience, making it more user-friendly.
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
2.1 Add homebre to your path:
If you’re using zsh, add Homebrew to your path to easily access its commands. If you are using a different shell, these commands will be different.
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
2.2 Install Essential Packages:
We’ll need Python, MariaDB, Redis, wkhtmltopdf, and pipx for our setup.
brew install python@3.11 mariadb@10.6 redis@6.2 wkhtmltopdf pipx
Follow homebrew’s instructions for adding MariaDB and Redis to your $PATH. For example (for zsh):
echo 'export PATH="/opt/homebrew/opt/mariadb@10.6/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/opt/homebrew/opt/redis@6.2/bin:$PATH"' >> ~/.zshrc
2.3 Set MariaDB Root Password:
To secure your MariaDB installation, set a root password. Replace $NEW_PASSWORD with your desired password.
sudo /opt/homebrew/opt/mariadb@10.6/bin/mysqladmin -u root password $NEW_PASSWORD
Note: this command needs to be run as the admin user.
2.4 Configure MariaDB:
Ensure MariaDB uses the appropriate character sets.
Add the following configurations into /opt/homebrew/etc/my.cnf.d/frappe.cnf:
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
bind-address = 127.0.0.1
[mysql]
default-character-set = utf8mb4
2.5 Restart MariaDB:
To apply the changes, restart MariaDB.
brew services restart mariadb@10.6
2.6 Install NVM (Node Version Manager):
NVM allows you to manage multiple Node.js versions.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
2.7 Install Essential Tools:
Next, we’ll install the bench CLI, process manager honcho, NodeJS v18, and the package manager yarn.
pipx install frappe-bench
pipx install honcho
nvm install 18
nvm use 18
npm i -g yarn
In order for the bench and honcho commands to become available, you might need to run pipx ensurepath and restart you terminal.
2.8 Setup Frappe/ERPNext:
Now, we’ll initialize a new bench and set up ERPNext. This can be done in any directory you like, for example ~/Code/Bench.
cd ~/Code/Bench # optional (create these directories beforehand)
# The `--no-backups` flag is used to avoid configuring crontab, which needs higher privileges.
bench init --python python3.11 --no-backups develop
cd develop/
bench get-app erpnext
bench new-site develop.localhost --install-app erpnext
bench start
3. Accessing Your Site:
After completing the above steps, your ERPNext site should be accessible at:
4. Special Tricks
4.1 Silence errors caused by RQ on Mac:
You’ll notice that you’ll frequently get “Python ended unexpectedly” error messages. To avoid this, add the following line to your shell configuration (for example ~/.zshrc) (source):
# Avoid "python ended unexpectedly" bug, caused by RQ
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
4.2 Always use the right node version:
When you’re using multiple versions of node, you’ll have to run nvm use [version] before you can use commands like bench build. To avoid this, you can add node to your virtualenv:
nvm use 18 # select the desired node version
ln -s $(which node) env/bin/node # link the specific node version in you virtualenv
ln -s $(which yarn) env/bin/yarn # link the specific yarn version in you virtualenv
Now whenever you activate your virtual environment (source env/bin/activate), you’ll be using not only the correct python but also the correct node and yarn.
4.3 Initialize benches with older versions:
For example, let’s get a bench named “version-14”, running frappe’s version-14-hotfix branch:
# install older dependencies
brew install python@3.10
nvm install 16
nvm use 16
npm i -g yarn
# initialize a bench with the specific branch
bench init --python python3.10 --no-backups --frappe-branch version-14-hotfix version-14