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 (and a bit easier).
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:
Note (April 2024): this has been integrated into the default
Procfileand is now obsolete.
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
cd version-14
# install an app with the specific branch
bench get-app erpnext --branch version-14-hotfix