ERPNext is a free and open-source integrated Enterprise Resource Planning (ERP) software used by manufacturers, distributors and services companies. It includes modules like accounting, CRM, sales, purchasing, website + e-commerce, point of sale, manufacturing, warehouse, project management, inventory and services. Also, it has domain specific modules like schools, healthcare, agriculture and non-profit.

This installation process works for both Ubuntu 16.04 and 18.04. However, at the time of this writing, Ubuntu 18.04 can only be used for local dev and using yourdomain:8000 but NOT for yourdomain.com (without using port 8000). When trying to install the production version (without port 8000) on Ubuntu 18.04, there seems to be a problem using the bench command (documented below) that is not present in 16.04.

ERPNext recommends that a VPS should have at least 1GB RAM but after I installed this (and multiple apps), RAM usage appeared to be between 1-2GB. Using 1GB RAM Bench could not completely load, so the minimum required should be 2GB RAM.

If using Vagrant for local dev, the Vagrantfile settings are below (you can use whatever port you like for host):

...

config.vm.network "forwarded_port", guest: 8000, host: 8000

...

config.vm.provider "virtualbox" do |vb|
  #   # Display the VirtualBox GUI when booting the machine
  #   vb.gui = true
  #
  #   # Customize the amount of memory on the VM:
    vb.memory = "2048"
  end
...

end

1. Install git

$ sudo apt-get install git

Check whether git has been installed correctly

$ git --version

You should then see git version X.Y.Z on your terminal screen.

2. Install Python. Frappé requires Python 2.7 to be installed:

$ sudo apt-get install python-dev

Install setuptools and pip (Python's Package Manager):

$ sudo apt-get install python-setuptools
$ sudo apt-get install python-pip

3. Install MariaDB 10.3 stable package:

$ 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 for the same, you'll have to initialize the MySQL server setup yourself after the above command completes. You can initialize the MySQL server setup by executing the following command mysql_secure_installation. Remember: only run it if you're not prompted for the password during setup.

Test whether the installation has worked:

$ mysql -u root -p -h localhost

You should be prompted for the mysql root password you have provided during the installation. Get back out of the mysql console by typing \q.

Next you'll need the MySQL database development files:

$ sudo apt-get install libmysqlclient-dev

You also need to edit the mariadb configuration:

$ sudo nano /etc/mysql/my.cnf

And add this to the file (I added this to the bottom of each section):

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

Ctrl-X, then ‘Y' to save and exit.Then restart the mysql server:

$ sudo service mysql restart

4. Install Redis:

$ sudo apt-get install redis-server

5. Install Node.js 8.X package:

$ sudo apt-get install curl
$ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
$ sudo apt-get install -y nodejs

6. Install yarn:

$ sudo npm install -g yarn

7. Installing Bench:

$ git clone https://github.com/frappe/bench

If you get an permission denied error, do this (see Error 3 below):

$ sudo chown -R $USER:$GROUP ~/.npm
$ sudo chown -R $USER:$GROUP ~/.config

Then delete the bench directory and re-install Bench:

$ sudo rm -R bench
$ git clone https://github.com/frappe/bench

Then run:

$ pip install -e ./bench

Check whether Bench has been installed correctly (you may wish to log out and log back into your terminal before this step, as this will refresh your environment variable, adding ~/.local/bin to your path if it not already there):

$ bench --version

8. Bench Quickstart

To create a new bench, simply use the bench init command as follows:

$ bench init --frappe-branch master frappe-bench

where frappe-bench is any name you want to call your bench.

Change to your bench directory:

$ cd frappe-bench

9. Add a site

new-site is the command to create the new site and site1.local is the name of the site:

$ bench new-site site1.local

You will be asked for the database password that you setup earlier when you installed MariaDB. You will also be asked to set an Administrator password for the site.

10. Add/Fetching apps

The get-app command fetches erpnext from the remote git repository and stores erpnext within your bench:

$ bench get-app --branch master erpnext

11. Install apps

To install an app on your new site, use the bench install-app command:

$  bench --site site1.local install-app erpnext

12. Start Bench

$ bench start

To login to ERPNext, open your browser and go to [your-external-ip]:8000, or localhost:8000

The default username (where it says email address) is “Administrator” and password is what you set when you created the new site.

Follow the install wizard prompts to setup ERPNext.

After going thru all the steps in the setup wizard, the setup failed.

Setup failed

Could not start up: Error in setup

SOLUTION: In the “Select your Domain” section of the wizard, I had to UNCHECK all items except 1 (ex. Services or Non-Profit) for the setup to complete. Then, go to My Settings > Setup > Domain Settings, and select the domain you desire. Make sure to refresh your desktop for the new icons to show.

13. Updating

To manually update the bench, run bench update to update all the apps, run patches, build JS and CSS files and restart supervisor (if configured to).

$ cd frappe-bench
$ bench update

You can also run the parts of the bench selectively.

only pull changes in the apps:

$ bench update --pull

only run database migrations in the apps:

$ bench update --patch

only build JS and CSS files for the bench:

$ bench update --build

only update the bench utility (this project):

$ bench update --bench

only update dependencies (python packages) for the apps installed:

$ bench update --requirements

14. Setup Production

https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development

To run ERPNext on yourdomain.com instead of yourdomain.com:8000 run the code below. Make sure you do not have the bench running and that you are in the frappe-bench directory. Substitute USER for your ubuntu username. Note that this code only worked for me on Ubuntu 16.04 and NOT 18.04. At the time of this writing, Ubuntu 18.04 can be used for local dev and using yourdomain:8000 but NOT for yourdomain.com (without using port 8000)

~/frappe-bench$ sudo bench setup production USER

That's it. You can now go to yourdomain.com and you will see the default website homepage. Go to the top right corner of the website to login or (if you are already logged in) select Switch to Desk located underneath your username.

15. Using Let's Encrypt to setup HTTPS

The only thing left would be to install an SSL certificate (ex. LetsEncrypt) so that you are accessing ERPNext with https instead of http.

https://frappe.io/docs/user/en/bench/guides/lets-encrypt-ssl-setup.html

Setup DNS Multitenant:

$ bench config dns_multitenant on

Then run (where site1.local is the name of the site name you created in the “Add a Site” section above):

$ sudo -H bench setup lets-encrypt site1.local

Respond to the prompts. This will also add an entry to the crontab of the user that will attempt to renew the certificate every month.

To renew certificates manually you can use:

$ sudo bench renew-lets-encrypt

16. Stopping Production and starting Development

$ cd frappe-bench
$ bench switch-to-develop
$ sudo rm config/supervisor.conf
$ sudo rm config/nginx.conf

Remove restart_supervisor_on_update from sites/common_site_config.json if it exists:

$ sudo nano sites/common_site_config.json

Then:

$ sudo service nginx stop
$ sudo service supervisor stop
$ bench setup procfile
$ bench start

ERRORS & SOLUTIONS

Error 1: ERPNext vagrant box error:

...
mount: unknown filesystem type 'vboxsf'
...

https://github.com/hashicorp/vagrant/issues/6769#issuecomment-252151694

You can also install the vagrant-vbguest plugin so it adds the VirtualBox Guest Additions for you.

$ vagrant plugin install vagrant-vbguest
$ vagrant destroy && vagrant up

Eliminated the error message. But the ERPNext vagrant box still would not work…

Error 2: ubuntu/bionic64 vagrant box (Ubuntu 18.04)

...
GuestAdditions seems to be installed (6.0.6) correctly, but not running.
...

https://github.com/dotless-de/vagrant-vbguest/issues/333#issuecomment-487105544

1. Navigate to problematic vagrant directory and uninstall vbguest:

$ vagrant plugin uninstall vagrant-vbguest

2. Add the following code to the respective Vagrantfile (credit to @alvaro-canepa). I added this to the bottom of Vagrantfile, just before the last end command.

if Vagrant.has_plugin?("vagrant-vbguest")
    config.vbguest.auto_update = false
end

3. Run the following:

$ vagrant halt
$ vagrant up

Eliminated the error message.

Error 3: Creating a new bench (Ubuntu 18.04)

When installing Bench, I ran this code:

$ bench init --frappe-branch master frappe-bench

and got this error:

...
An unexpected error occurred: "EACCES: permission denied, scandir '/home/vagrant/.config/yarn/link'".
...

https://stackoverflow.com/questions/49529696/yarn-error-eaccess-permission-denied-scandir-home-ubuntu-config-yarn-link

Run the following command:

$ sudo chown -R $USER:$GROUP ~/.npm
$ sudo chown -R $USER:$GROUP ~/.config

This worked and the Bench install completed with no more errors.

Error 4: Adding apps (Ubuntu 18.04)

Ran this code (1):

$ bench get-app erpnext https://github.com/frappe/erpnext

and got this error:

Error: File to import not found or unreadable: frappe/public/scss/variables.
...
UNRESOLVED_IMPORT : 'vue-router/dist/vue-router.js' is imported by ../erpnext/erpnext/public/js/education/lms/lms.js, but could not be resolved – treating it as an external dependency
Cannot find some dependencies. You may have to run "bench setup requirements" to install them.

MISSING_GLOBAL_NAME : No name was provided for external module 'vue-router/dist/vue-router.js' in output.globals – guessing 'VueRouter'

Ran the command:

$ bench setup requirements

DID NOT correct the errors.

Ran this code (2):

First, remove the app from the bench:

$ bench remove-app erpnext

Then run this command:

$ bench get-app --branch master erpnext

No errors.

Error 5: Installing Apps (Ubuntu 18.04)

Ran this code:

$ bench --site site1.local install-app erpnext

got these errors:

Installing erpnext...
Traceback (most recent call last):
  File "/usr/lib/python2.7/runpy.py", line 174, in _run_module_as_main
    "__main__", fname, loader, pkg_name)
  File "/usr/lib/python2.7/runpy.py", line 72, in _run_code
    exec code in run_globals
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/utils/bench_helper.py", line 97, in <module>
    main()
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/utils/bench_helper.py", line 18, in main
    click.Group(commands=commands)(prog_name='bench')
  File "/home/vagrant/frappe-bench5/env/local/lib/python2.7/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/home/vagrant/frappe-bench5/env/local/lib/python2.7/site-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/home/vagrant/frappe-bench5/env/local/lib/python2.7/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/vagrant/frappe-bench5/env/local/lib/python2.7/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/vagrant/frappe-bench5/env/local/lib/python2.7/site-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/vagrant/frappe-bench5/env/local/lib/python2.7/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/home/vagrant/frappe-bench5/env/local/lib/python2.7/site-packages/click/decorators.py", line 17, in new_func
    return f(get_current_context(), *args, **kwargs)
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/commands/__init__.py", line 25, in _func
    ret = f(frappe._dict(ctx.obj), *args, **kwargs)
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/commands/site.py", line 168, in install_app
    _install_app(app, verbose=context.verbose)
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/installer.py", line 143, in install_app
    add_module_defs(name)
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/installer.py", line 342, in add_module_defs
    d.save(ignore_permissions=True)
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/model/document.py", line 260, in save
    return self._save(*args, **kwargs)
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/model/document.py", line 283, in _save
    self.insert()
  File "/home/vagrant/frappe-bench5/apps/frappe/frappe/model/document.py", line 237, in insert
    raise e
frappe.exceptions.DuplicateEntryError: (u'Module Def', u'Accounts', IntegrityError(1062, u"Duplicate entry 'Accounts' for key 'PRIMARY'"))

bench uninstall-app erpnext

Then reinstalled erpnext:

$ bench --site site1.local install-app erpnext

REFERENCES

https://erpnext.org/
https://erpnext.com/
https://github.com/frappe/erpnext
https://github.com/frappe/frappe/wiki/The-Hitchhiker%27s-Guide-to-Installing-Frapp%C3%A9-on-Linux
https://github.com/frappe/bench
https://frappe.io/docs/user/en/bench/guides/setup-production.html
https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development
https://frappe.io/docs/user/en/bench/guides/lets-encrypt-ssl-setup.html
https://frappe.io/docs/user/en/bench/guides/setup-multitenancy
https://frappe.io/docs/user/en/bench/guides/adding-custom-domains.html

also for ubuntu 18.04, see:
https://www.rosehosting.com/blog/how-to-install-erpnext-on-ubuntu-18-04/

Hosting

This web app has been tested on DigitalOcean. This app can also be installed using other hosts such as Amazon AWS, Google Cloud, Microsoft Azure, Vultr and others.

Installation & Maintenance

If you would like to get this app installed, maintained or need training, Contact Me to get current rates.