Frappe and ERPNext are amazing for small to medium scale enterprises, But one thing I’ve noticed is it’s lack of proper documentation. Many discussions are spread across their multiple forums and GitHub repositories.

Frappe can hold multiple sites and applications inside bench, package manager of Frappe. We could manage multiple sites and applications within a single bench, using the bench command. So, we’ve to first install the bench.

Note: There doesn’t seem to any information regarding release process of any of the Frappe components., Other than few thread on forum.auto_updates can also mess up the installation later on, we’ll get to that soon.

Prerequisites

  • Ubuntu LTS
  • Python
  • Redis
  • MariaDB 10.3

Some dependencies and versions are unavailable on Ubuntu 18.04 LTS core repository, So it might need some additional setups. Here we’re sticking to 16.04 LTS.

sudo apt update

(Optional): Some VPS, like GCE may have issues with locales

sudo apt install locales && sudo locale-gen en_US.UTF-8

Install dependenies

sudo apt install -y \
    git curl vim htop software-properties-common \
    python3-dev python3-setuptools python3-pip \
    redis-server nginx supervisor

Configure package repositories to install MariaDB and NodeJS.

sudo apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xF1656F24C74CD1D8
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo add-apt-repository \
    "deb [arch=amd64,arm64,ppc64el] \
    http://sfo1.mirrors.digitalocean.com/mariadb/repo/10.3/ubuntu \
    $(lsb_release -cs) \
    main"
sudo apt update
sudo apt install -y mariadb-server-10.3 libmysqlclient-dev nodejs
sudo npm install -g yarn

Notes

  • Set MySql root password when prompted during installation, If it wasn’t prompted, run mysql_secure_installation
  • Since we installed yarn with sudo npm, /.config would be owned by root user. Change the ownership to current user. Else it might break bench initialisation. If you don’t prefer to use npm with sudo, Use nvm to install LTS version of node
sudo chown $USER:$USER ~/.config
  • Modify MySql configuration at /etc/mysql/my.cnf to include the following,
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

Restart MySql for these configuations to take effect,

sudo service mysql restart

Installing Bench

Like mentioned before, It’s confusing to choose the right version of this tool. Because, there are tons of useful features in master that are missing from releases.

It’s better to install from repository than depending on these releases,

git clone https://github.com/frappe/bench
sudo -H pip install -e ./bench

You could skip sudo here, But then other users won’t be able to use the bench command. Or better yet we could configure bench_manager to manage sites and applications from web interface.

Verify bench is available with bench --version

Initialize Bench

Now we need to initialize bench with a target directory. This would clone and install Frappe and related structure to that directory. But, the default branch of Frappe is development, which would install Frappe from unstable development branch on our server

Bench compiled from source has flags to choose installation branch of Frappe and ERPNext, but the releases versions don’t. We’ll install from the master branch (v11 now).

bench init --frappe-branch master frappe_bench --python `which python3`

If you want Frappe from older branch like v10.x.x, pass it as argument to bench init. I must say, even though it’s not the latest release stick with v10 if you’re not going to properly patch v11. Hopefully v10 might be LTS release. There are no confirmation from core team regarding this.

If it failed run bench setup requirements from inside the directory or remove that directory and restart.

Installing Apps

Change to Frappe Bench directory

cd frappe_bench

Add applications to Bench

bench get-app erpnext --branch master

Add sites to bench

bench new-site erp.example.com

This will ask for administrator password, You would need this for first login. Also don’t open the url yet, Few more step.

Add applications to site

bench --site erp.example.com install-app erpnext

Now erpnext is installed to that domain. We could test that by starting development server usingbench start. ERPNext would be available at http://erp.example.com:8000

Configuring Bench Manager

bench get-app bench_manager
bench new-site bench.example.com
bench --site bench.example.com install-app bench_manager

Setting up for production

Configuring Bench

bench config auto_update off
bench config dns_multitenant on

Install Let’s Encrypt certificate

sudo -H bench setup lets-encrypt erp.example.com
sudo -H bench setup lets-encrypt bench.example.om

Setup nginx and supervisor

bench setup nginx
bench setup supervisor

Link relevant configuration files

sudo ln -s $PWD/config/nginx.conf /etc/nginx/conf.d/frappe-bench.conf
sudo ln -s $PWD/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf

Restart services for these configuations to take effect,

sudo service nginx restart
sudo service suprevisor restart