Installation
These steps assume you want to install Bench in developer mode. If you want install in production mode, follow the latest recommended installation methods.
System Requirements
This guide assumes you are using a personal computer, VPS or a bare-metal server. You also need to be on a *nix system, so any Linux Distribution and MacOS is supported. However, we officially support only the following distributions.
Learn more about the architecture here.
Pre-requisites
Python 3.6+
Node.js 14
Redis 6 (caching and realtime updates)
MariaDB 10.3.x / Postgres 9.5.x (to run database driven apps)
yarn 1.12+ (js dependency manager)
pip 20+ (py dependency manager)
wkhtmltopdf (version 0.12.5 with patched qt) (for pdf generation)
cron (bench's scheduled jobs: automated certificate renewal, scheduled backups)
NGINX (proxying multitenant sites in production)
MacOS [Intel Processor]
Install Homebrew. It makes it easy to install packages on macOS.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Now, you can easily install the required packages by running the following command
brew install python git redis mariadb@10.3
brew install --cask wkhtmltopdf
Now, edit the MariaDB configuration file.
nano /usr/local/etc/my.cnf
And add this configuration
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql]
default-character-set = utf8mb4
Now, just restart the mysql service and you are good to go.
brew services restart mariadb
Install Node
We recommend installing node using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
After nvm is installed, you may have to close your terminal and open another one. Now run the following command to install node.
nvm install 14
Verify the installation, by running:
node -v
# v14.xx.x
Finally, install yarn using npm
npm install -g yarn
MacOS [M1]
Install Rosetta
/usr/sbin/softwareupdate --install-rosetta --agree-to-license
Make a “Rosetta” version of your terminal:
Go to your “Applications” folder on Finder → right click Terminal in the “Utilities” folder → Duplicate → rename to “Rosetta Terminal” → Get Info → Open using > Rosetta
Install Homebrew in the Rosetta Terminal:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Install Required Packages
All the packages need to be installed in the Rosetta Terminal
brew install python git redis mariadb
brew install --cask wkhtmltopdf
Now, edit the MariaDB configuration file.
nano /usr/local/etc/my.cnf
And add this configuration
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb-read-only-compressed=OFF
[mysql]
default-character-set = utf8mb4
Now, just restart the mysql service and you are good to go.
brew services restart mariadb
Install Node
We recommend installing node using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
After nvm is installed, you may have to close your terminal and open another one. Now run the following command to install node.
nvm install 14
Verify the installation, by running:
node -v
# v14.xx.x
Finally, install yarn using npm
npm install -g yarn
Debian / Ubuntu
Install git
, python
, and redis
apt install git python-dev redis-server
Install MariaDB
apt-get install software-properties-common
If you are on Ubuntu version older than 20.04, run this before installing MariaDB:
apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xF1656F24C74CD1D8
add-apt-repository 'deb [arch=amd64,i386,ppc64el] http://ftp.ubuntu-tw.org/mirror/mariadb/repo/10.3/ubuntu xenial main'
If you are on version Ubuntu 20.04, then MariaDB is available in default repo and you can directly run the below commands to install it:
apt-get update
apt-get install mariadb-server-10.3
During this installation you'll be prompted to set the MySQL root password. If you are not prompted, you'll have to initialize the MySQL server setup yourself. You can do that by running the command:
mysql_secure_installation
Remember: only run it if you're not prompted the password during setup.
It is really important that you remember this password, since it'll be useful later on. You'll also need the MySQL database development files.
apt-get install libmysqlclient-dev
Now, edit the MariaDB configuration file.
nano /etc/mysql/my.cnf
And add this configuration
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql]
default-character-set = utf8mb4
Now, just restart the mysql service and you are good to go.
service mysql restart
Install Node
We recommend installing node using nvm
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
After nvm is installed, you may have to close your terminal and open another one. Now run the following command to install node.
nvm install 14
Verify the installation, by running:
node -v
# output
v14.17.2
Finally, install yarn
using npm
npm install -g yarn
Install wkhtmltopdf
apt-get install xvfb libfontconfig wkhtmltopdf
Arch Linux
Install packages using pacman
pacman -Syu
pacman -S mariadb redis python2-pip wkhtmltopdf git npm cronie nginx openssl
npm install -g yarn
Setup MariaDB
mysql_install_db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
systemctl start mariadb
mysql_secure_installation
Edit the MariaDB configuration file
nano /etc/mysql/my.cnf
Add the following configuration
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql]
default-character-set = utf8mb4
Start services
systemctl start mariadb redis
If you don't have cron service enabled you would have to enable it.
systemctl enable cronie
Fedora
Install required packages using dnf.
dnf install mariadb mariadb-server yarnpkg nodejs redis cronie
Setup MariaDB
systemctl start mariadb
mysql_secure_installation
Open MySQL configuration file
nano /etc/my.cnf
and add the following lines
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql]
default-character-set = utf8mb4
Start MariaDB and Redis services
systemctl start mariadb redis
Install Bench CLI
Install bench via pip3
pip3 install frappe-bench
Confirm the bench installation by checking version
bench --version
# output
5.2.1
Create your first bench folder.
cd ~
bench init frappe-bench
After the frappe-bench folder is created, change your directory to it and run this command
bench start
Congratulations, you have installed bench on to your system.