Installation

These steps assume you want to install Bench in developer mode. If you want install in production mode, follow the Easy Install method.

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.

  1. MacOS
  2. Debian / Ubuntu
  3. Arch Linux
  4. CentOS

Learn more about the architecture here.

Pre-requisites

  1. Python 2.7 (Python 3.5+ also supported)
  2. MariaDB 10+
  3. Nginx (for production)
  4. Git
  5. Nodejs
  6. yarn
  7. Redis
  8. cron (crontab is required)
  9. wkhtmltopdf with patched Qt (version 0.12.3) (for pdf generation)

MacOS

Install Homebrew. It makes it easy to install packages on macOS.

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

Now, you can easily install the required packages by running the following command

brew install python
brew install git
brew install redis
brew install mariadb

brew tap caskroom/cask
brew cask install wkhtmltopdf

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 8

Verify the installation, by running:

node -v
# output
v8.11.3

Finally, install yarn using npm

npm install -g yarn

Debian / Ubuntu

Install git, python, and redis

sudo apt install git python-dev redis-server

Install MariaDB

sudo apt-get install software-properties-common
sudo apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xF1656F24C74CD1D8
sudo add-apt-repository 'deb [arch=amd64,i386,ppc64el] http://ftp.ubuntu-tw.org/mirror/mariadb/repo/10.3/ubuntu xenial main'
sudo apt-get update
sudo 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.

sudo apt-get install libmysqlclient-dev

Now, edit the MariaDB configuration file.

sudo 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 good

sudo 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 8

Verify the installation, by running:

node -v
# output
v8.11.3

Finally, install yarn using npm

npm install -g yarn

Install wkhtmltopdf

sudo 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]
innodb-file-format=barracuda
innodb-file-per-table=1
innodb-large-prefix=1
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

Install Bench

Install bench as a non-root user

git clone https://github.com/frappe/bench bench-repo
pip install --user -e bench-repo

Confirm the bench installation by checking version

bench --version

# output
4.1.0

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.