Skip to content

Installation Guide

Jump to bottom
Saif Ur Rehman edited this page Apr 10, 2025 · 16 revisions

These steps assume you want to install Bench in developer mode. If you want install in production mode, follow the latest recommended installation methods.

Learn more about the architecture here.

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. Debian / Ubuntu

This guide is tested on Ubuntu 20.04

Pre-requisites

Python 3.10+ (Python 3.11+ recommended)
Node.js 18+
Redis 6+                                      (caching and realtime updates)
MariaDB 10.6.6+                               (Database backend)
yarn 1.12+                                    (js dependency manager)
pip 20+                                       (py dependency manager)
wkhtmltopdf (version 0.12.6 with patched qt)  (for pdf generation)
cron                                          (bench's scheduled jobs: automated certificate renewal, scheduled backups)
NGINX                                         (proxying multitenant sites in production)

Install Required Packages

Install git

sudo apt install git

Install curl

sudo apt install curl

Install Python (python3.11)

sudo apt install python3 python3-dev python3.11-dev python3-setuptools python3-pip python3-distutils python3.11-venv

Install Redis Server

sudo apt install redis-server

Install Software Properties Common (for repository management)

sudo apt install software-properties-common

Install Node

We recommend installing node using nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

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 18

Verify the installation, by running:

node -v

Install yarn using npm

npm install -g yarn

Install wkhtmltopdf

Download wkhtmltopdf dependencies and fonts

sudo apt install xvfb fontconfig libxrender1 libfontconfig xfonts-75dpi

Download wkhtmltopdf from https://wkhtmltopdf.org/downloads.html

Ubuntu 22.04 amd64 file

curl https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb -L -o wkhtmltox_0.12.6.1-2.jammy_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb

https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb

Install and Configure MariaDB

Install MariaDB (mariadb-server-10.6+)

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:

sudo apt install mariadb-server-10.6

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:

sudo 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 install mariadb-client

Now, edit the MariaDB configuration file.

sudo nano /etc/mysql/mariadb.cnf

And add this configuration at the END of the file

[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.

sudo service mariadb restart

Install Bench CLI

Install bench via pip3

sudo pip3 install frappe-bench

Confirm the bench installation by checking version

bench --version

Setup a new bench environment

Create a directory for all frappe projects

cd ~
mkdir frappe
cd frappe

Create your first bench environment / folder

bench init frappe-bench --frappe-path https://github.com/ParaLogicTech/frappe.git --frappe-branch version-15 --python python3.11
cd frappe-bench

After the frappe-bench folder is created, download frappe applications (optional)

bench get-app payments
bench get-app https://github.com/ParaLogicTech/crm.git --branch version-15
bench get-app https://github.com/ParaLogicTech/erpnext.git --branch version-15

Setup a new site (database)

bench new-site paralogic.v15 --db-name paralogic_v15_erp

Set the paralogic.v15 site as the default site for this bench

bench use paralogic.v15

Add site in hosts file

sudo nano /etc/hosts

and add the line

127.0.0.1       paralogic.v15

or use bench command to add site to hosts file

bench add-to-hosts

Install applications on site paralogic.v15

bench install-app erpnext

Start bench (development mode)

While inside your bench directory you can run bench commands. To start the bench servers run the command

bench start

After starting the bench you will see that web server will be running on port 8000 or higher

22:46:32 web.1            |  * Running on all addresses (0.0.0.0)
22:46:32 web.1            |  * Running on http://127.0.0.1:8000
22:46:32 web.1            |  * Running on http://10.0.2.15:8000

Access the site using a web browser from the hostname you set in hosts file

http://paralogic.v15:8000

Congratulations, your bench is now installed and working on your system.

Enable developer_mode configuration

nano sites/common_site_config.json

Change developer_mode value to 1 or use bench command to enable developer_mode

bench set-config developer_mode 1

Clone this wiki locally