ERPNext - Virtual Machine released!

The core ERPNext team are moving to docker as their preferred deployment architecture and have removed the Virtual Machine (VM) download for people wanting an easy entry into frappe or ERPNext ownership. So we thought we would build a minimal VM to make your life a bit easier.

We have tested the VM for use with ERPNext versions 11 to 15, but it will be useful for versions even older than that.

Hardware requirements

The Virtual Machine is configured with 1 CPU core, 1.5GB RAM and 30GB disk space. Any computer since 2010 should be able to run it with at least 2GB RAM. The Virtual Machine OVA file download is 5GB but will extract larger than that when you import it and will use more disk space as you build and use.

Disclaimer

The security settings of the Virtual Machine are not suitable for a hostile environment like the internet. It comes with no warranty or support but let us know here if you have problems (or not!) and we'll see what we can do to help.

Pre-requisites

1. First you'll need to download and install some host software. We recommend VirtualBox.
2. Next you need to download our Virtual Machine.
3. Then import it into VirtualBox and start it up. NOTE: the VM is configured for a NAT network interface by default.
4. If you're on Windows, you may need to install putty to make an ssh connection.

Connect via ssh

Whilst you can use the console that pops up to run the commands later on, we recommend connecting via ssh. Ssh port 22 is already forwarded to host port 2222, so connect using these settings:

1. Port: 2222
2. Host: localhost or 127.0.0.1
3. User: frappe
4. Password: frappe (use this for sudo commands too)

Warning: See the end of the guide for a potential networking problem

Building a bench

First you need to pick a frappe version. At time of writing (November 2022) version 14 is the latest.

Update: As of July 2024, version 15 is mature enough to try.

If you're trying to restore an existing backup, you should pick the major version that is the same as the database. You can find this out by going to Help -> About and looking at the Frappe Framework number. The ERPNext major version should be the same.

In all of the below commands, if you just want to use frappe and not ERPNext, you can remove the --install-app erpnext parts.

Switch node/yarn versions:

For frappe versions between 12 and 14 inclusive, you can use node.js version 14:

$ nvm list
$ nvm use 14
$ nvm alias default 14

Version-15 bench:

You will need to install node version 18 for frappe version 15:

$ nvm install 18
$ nvm use 18
$ bench init --python /usr/bin/python3.10 --version version-15 --install-app erpnext v15
$ cd v15
$ bench get --branch version-15 payments
$ bench get --branch version-15 webshop

Version-14 bench:

$ bench init --python /usr/bin/python3.10 --version version-14 --install-app erpnext v14
$ cd v14
$ bench get --branch version-14 payments

Version-13 bench:

$ bench init --python /usr/bin/python3.9 --version version-13 --install-app erpnext v13

Version-12 bench:

$ bench init --python /usr/bin/python3.9 --version version-12 --install-app erpnext v12

Version-11 bench:

$ nvm use 8
$ bench init --python /usr/bin/python3.7 --version version-11 --install-app erpnext v11

Warning: At time of writing version-11 will fail to build. Simply answer N to the question Do you want to rollback these changes? to keep the bench. Now you must downgrade the python MarkupSafe package & rebuild like this:

$ cd v11
$ ./env/bin/python -m pip install -U "MarkupSafe<2.1.0"
$ bench build

Creating a fresh site

You can create a fresh site with the commands below.

Name your site whatever you want, but if you plan to change the configuration to use DNS based routing (rather than the default port-based routing) you should pick your planned domain name. Like erp.domain.com. The bench directory will be one of v11, v12, v13, v14, etc.

$ cd <bench directory>
$ bench new-site --install-app erpnext <site name>

The MySQL root password is frappe

Add --install-app <app> options for any other apps you have installed, like payments and webshop.

You will need to set up port number 80 for your site. The Virtual Machine is already set to redirect port 8080 on your host machine to port 80.

$ bench set-nginx-port <site name> 80
$ sudo bench setup production frappe
$ sudo bench setup sudoers frappe
$ sudo supervisorctl reread
$ sudo supervisorctl reload
$ bench restart

If you get an error here try the following:

$ sudo rm /etc/supervisor/conf.d/*
$ sudo ln -s /home/frappe/<bench>/config/supervisor.conf <bench>.conf

Then run the last three commands above.

Restoring a backup

First you will need to get copies of your database and file archives onto the VM. Look up how to use scp (secure copy) which will transfer the files from your local machine over ssh to the VM.

$ bench --site <site name> restore <path/to/database.sql.gz> --with-private-files <path/to/private-files.tar.gz> --with-public-files <path/to/files.tar.gz>

Depending on the size of the database and file archives this could take a while.

You will also need to copy your encryption key from your site config text file backup into the site_config.json file. It should look like this:

...
 "db_type": "mariadb",
 "encryption_key": "LoNgStRiNgHeRe",
 "pause_scheduler": 0,
...

Nano is a simple to use command-line text editor:

$ nano ./sites/<site name>/site_config.json

Use your arrow keys to scroll around and edit the file. Create a new line or replace the existing encryption key if there is one by pasting the key to where the cursor is. Be careful with the commas at the end of the lines.

CTRL+o to save and CTRL+x to exit.

Starting the scheduler

By default the scheduler will not run so things like backups and sending emails will not happen, but frappe and ERPNext will otherwise run fine. If you want to start it run this:

$ bench --site <site name> enable-scheduler

Problems

There has been a report that networking does not work. It turns out this is caused by the deletion of the /etc/machine-id file before publishing.

Simply run the following as root:

$ systemd-machine-id-setup
$ shutdown -r now
$ journalctl -b -u systemd-networkd

Congratulations!

You can now connect to your new virtual machine here: http://localhost:8080

Welcome to the future of web app and ERP software!